view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        lock for each write. "exclusive" acquires the lock at object
        creation and holds it until the the object is destroyed.

        Lock file is named "<prefix>"".lck". Will wait for up to 1 minute to
        acquire lock, will die if failed to acquire lock.

    *   hook_before_write => CODE

    *   hook_before_rotate => CODE

    *   hook_after_rotate => CODE

    *   hook_after_create => CODE

        See "ATTRIBUTES".

    *   buffer_size => int

    *   rotate_probability => float (between 0 < x < 1)

        If set, instruct to only check for rotation under a certain
        probability, for example if value is set to 0.1 then will only check
        for rotation 10% of the time.

  lock_file_path => STR
    Returns a string representing the complete pathname to the lock file,
    based on "dir" and "prefix" attributes.

  $fwr->write(@args)
    Write to file. Will automatically rotate file if period changes or file
    size exceeds specified limit. When rotating, will only keep a specified
    number of histories and delete the older ones.

    Does not append newline so you'll have to do it yourself.

  $fwr->compress
    Compress old rotated files and remove the uncompressed originals.
    Currently uses IO::Compress::Gzip to do the compression. Extension given
    to compressed file is ".gz".

    Will not lock writers, but will create "<prefix>""-compress.pid" PID
    file to prevent multiple compression processes running and to signal the
    writers to postpone rotation.

    After compression is finished, will remove the PID file, so rotation can
    be done again on the next "write()" if necessary.

FAQ
  Why use autorotating file?
    Mainly convenience and low maintenance. You no longer need a separate
    rotator process like the Unix logrotate utility (which when accidentally
    disabled or misconfigured will cause your logs to stop being rotated and
    grow indefinitely).

  What is the downside of using FWR (and LDFR)?
    Mainly (significant) performance overhead. At (almost) every "write()",
    FWR needs to check file sizes and/or dates for rotation. Under default
    configuration (where "lock_mode" is "write"), it also performs locking
    on each "write()" to make it safe to use with multiple processes. Below
    is a casual benchmark to give a sense of the overhead, tested on my Core
    i5-2400 3.1GHz desktop:

    Writing lines in the size of ~ 200 bytes, raw writing to disk (SSD) has
    the speed of around 3.4mil/s, while using FWR it goes down to around
    ~13k/s. Using "lock_mode" "none" or "exclusive", the speed is ~52k/s.

    However, this is not something you'll notice or need to worry about
    unless you're writing near that speed.

    If you need more speed, you can try setting "rotate_probability" which
    will cause FWR to only check for rotation probabilistically, e.g. if you
    set this to 0.1 then checks will only be done in about 1 of 10 writes.
    This can significantly reduce the overhead and increase write speed
    several times (e.g. 5-8 times), but understand that this will make the
    writes "overflow" a bit, e.g. file sizes will exceed for a bit if you do
    size-based rotation. More suitable if you only do size-based rotation
    since it is usually okay to exceed sizes for a bit.

  I want a filehandle instead of a File::Write::Rotate object!
    Use Tie::Handle::FileWriteRotate.

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/File-Write-Rotate>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-File-Write-Rotate>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=File-Write-Rotate>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

SEE ALSO
    Log::Dispatch::FileRotate, which inspires this module. Differences
    between File::Write::Rotate (FWR) and Log::Dispatch::FileRotate (LDFR)
    are as follows:

    *   FWR is not part of the Log::Dispatch family.

        This makes FWR more general to use.

        For using together with Log::Dispatch/Log4perl, I have also written
        Log::Dispatch::FileWriteRotate which is a direct (although not a
        perfect drop-in) replacement for Log::Dispatch::FileRotate.

    *   Secondly, FWR does not use Date::Manip.

        Date::Manip is relatively large (loading Date::Manip 6.37 equals to
        loading 34 files and ~ 22k lines; while FWR itself is only < 1k
        lines!)

        As a consequence of this, FWR does not support DatePattern; instead,
        FWR replaces it with a simple daily/monthly/yearly period.

    *   And lastly, FWR supports compressing and rotating compressed old
        files.