Help language development. Donate to The Perl Foundation

IO::Handle::Rollover cpan:ATROXAPER last updated on 2020-12-29


Build Status


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


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;


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.


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))

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


Mikhail Khorkov [email protected]

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


Copyright 2020 Mikhail Khorkov

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