NAME

IO::Handle::Rollover - IO::Handle for rollover files (logs, for example) based on its size or creation time.

SYNOPSIS

use IO::Handle::Rollover;

# Open output.txt file for writing and auto rollover it
# after 30M size has been reached. Store only ten last files.
my $h = open('output.txt', :w, :rollover, :file-size<30M>, :10history-size);

$h.close; # do rollover after close;

DESCRIPTION

IO::Handle::Rollover provides an open method with :rollover parameter:

multi sub open(
  IO() $path,
  :$rollover! where * == True,
  Str :$file-size, # approximately maximum size of each file
  Int :$rotation-time, # time between rotations, starts from midnight + $midnight-offset
  Int:D :$history-size = 0, # maximum amount of files
  :&callback = -> $path { }, # callback with one positional arg - name of closed file
  Int:D :$midnight-offset = 0, # when midnight starts, in seconds
  :&ticker = -> { time }, # the custom way to provide current time in seconds
  Str :$suffix-style,
  :$async = False,
  |c # parameters for open each file through general open routine
)

Rollover bases on maximum file size or time limiter. You can use :$file-size and :$rotation-time accordingly.

File size accepts values like 3B, 4K, 5M or 6G for corresponding amount of bytes, kilobytes, megabytes and gigabytes accordingly. The file's concrete size can be a little bit more the value because the file will be rotated only after the limit reach.

Rotation time is an integer value in seconds describe how ofter the file will be rotated. The file's concrete rotate time can be slightly after the value because the file will be rotated only after the limit reach. You can use :$midnight-offset argument to set the preferable 'midnight'. It is useful if you want to rollover the file each day at 3 am, then pass :86400rotation-time, :10800midnight-offset. You can also provide the custom :$ticker - routine, which returns 'current' time in seconds.

:$history-size describes the maximum amount of the last rollover files. Zero meens infinite. The oldest file will be deleted after the limit reach.

:$suffix-style may have 'time' or 'order' value. In the 'time' case, rollover files will have _YYYY_MM_DDTHH_MM_SS suffix. In the 'order' case - _N suffix, where N is the number (starts from 1), the smaller, the more recent the file is. In other words, in the 'order' case, each file renames from _N to _{N+1} before each rollover. The default value is 'time' for time-based rollover and 'order' for size-based rollover.

You can provide :&callback routine with a single argument - the new closed file. The callback will be called after each file close and rename. You can use it for your custom purpose, for example, to archive the file.

If you want to write in asynchronous mode, then pass :async arg.

Any other named argument will be pass to general open routing to open each new file. :truncate argument means there will be no any new files - the $path file will be recreated after time or size limit reach.

USE FOR LOGGING

You can use IO::Handle::Rollover as any other output handles, but it is more useful in log systems.

For example, in the Log::Async:

use Log::Async;
use IO::Handle::Rollover;

logger.send-to(open("log.txt", :w, :rollover, :60rotation-time));
info "info";

Or in the LogP6:

use LogP6 :configure;
use IO::Handle::Rollover;

set-default-handle(open("log.txt", :w, :rollover, :60rotation-time))
get-logger("").info("info");

Or in the LogP6 configuration file:

{
...
  "handle": {
    "type": "custom",
    "require": "IO::Handle::Rollover",
    "fqn-method": "IO::Handle::Rollover::EXPORT::DEFAULT::&open",
    "positional": [ "log.txt" ],
    "args": {
      "w": true,
      "rollover": true,
      "file-size": "10M",
      "history-size": 3
    }
  }
...
}

AUTHOR

Mikhail Khorkov atroxaper@cpan.org

Source can be located at: github. Comments and Pull Requests are welcome.

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.