NAME
    FML::Cache::Ring - IO operations to ring buffer which consists of files.

SYNOPSIS
       ... lock e.g. by flock(2) ...

       use FML::Cache::Ring;
       $obj = new FML::Cache::Ring {
           directory          => '/some/where' # mandatory
           sequence_file_name => '.seq',       # optional
           modulus            => 128,          # optional
       };
       $fh = $obj->open;
       print $fh "some message";
       $fh->close;

       ... unlock ...

    The buffer directory has files with the numeric name 0, 1, ... You can
    specify "file_name" parameter.

       $obj = new FML::Cache::Ring {
           directory => '/some/where',
           file_name => '_smtplog',
       };

    If specified, the file names become _smtplog.0, _smtplog.1, ...

    The cache data is limited by the number of files, so approximately size
    by default.

    Instead of number fo files, you can limit FML::Cache::Ring based on
    time. It is time based expiretion. To specify based expiration, use
    new() like this:

       $obj = new FML::Cache::Ring {
           directory  => '/some/where',
           cache_type => 'temporal',
           expires_in => 90,             # 90 days
       };

    where "cache_type" is "cyclic" by default.

DESCRIPTION
    To log messages up to some limit, it may be useful to use filenames in
    cyclic way. The file to write is chosen among a set of files allocated
    as a buffer.

    Consider several files under a directory "ring/" as a ring buffer where
    the unit of the ring is 5 here. "ring/" may have 5 files in it.

       0 1 2 3 4

    To log a message is to write it to one of them. At the first time the
    message is logged to the file 0, and next time to 1 and so on. If all 5
    files are used, this module reuses and overwrites the oldest one 0. So
    we use a file in cyclic way as follows:

       0 -> 1 -> 2 -> 3 -> 4 -> 0 -> 1 -> ...

    We expire the old data. A file name is a number for simplicity. The
    latest number is holded in "ring/.seq" file (".seq" in that direcotry by
    default) and truncated to 0 by the modulo 5.

METHODS
  new(args)
    $args hash can take the following arguments:

            variable                default value
            --------------------------------
            directory               .
            file_name               ""
            sequence_file_name      .seq
            modulus                 128
            cache_type              cyclic
            dir_mode                0755

  open(file, mode)
    open file in the buffer. The target file is already determined when our
    constructor runs.

  close()
    no argument.

  add($args)
    import data into cache from file. Actually, link(2) $src to cache file.

        KEY        VALUE
        ---------------------------
        file       STR
        try_link   STR ( yes | no )

  get(key)
    get value (latest value in the ring buffer) for the key.

  find(key)
    get value (latest value in the ring buffer) for key. same as get() now.

  set(key, value)
    set value for key.

TODO
    Export core parts of this module to another putlic class e.g.
    File::SOMETHING outside FML::* classes, again.

CODING STYLE
    See "http://www.fml.org/software/FNF/" on fml coding style guide.

AUTHOR
    Ken'ichi Fukamachi

COPYRIGHT
    Copyright (C) 2004,2005,2006 Ken'ichi Fukamachi

    All rights reserved. This program is free software; you can redistribute
    it and/or modify it under the same terms as Perl itself.

HISTORY
    FML::Cache::Ring first appeared in fml8 mailing list driver package. See
    "http://www.fml.org/" for more details.

    FML::Cache::Ring is renamed from File::CacheDir in 2004.