#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#  (C) Paul Evans, 2012-2015 -- leonerd@leonerd.org.uk

package IO::Async::File;

use strict;
use warnings;

our $VERSION = '0.74';

use base qw( IO::Async::Timer::Periodic );

use Carp;
use File::stat;

# No point watching blksize or blocks
my @STATS = qw( dev ino mode nlink uid gid rdev size atime mtime ctime );

=head1 NAME

C<IO::Async::File> - watch a file for changes


 use IO::Async::File;

 use IO::Async::Loop;
 my $loop = IO::Async::Loop->new;

 my $file = IO::Async::File->new(
    filename => "config.ini",
    on_mtime_changed => sub {
       my ( $self ) = @_;
       print STDERR "Config file has changed\n";
       reload_config( $self->handle );

 $loop->add( $file );



This subclass of L<IO::Async::Notifier> watches an open filehandle or named
filesystem entity for changes in its C<stat()> fields. It invokes various
events when the values of these fields change. It is most often used to watch
a file for size changes; for this task see also L<IO::Async::FileStream>.

While called "File", it is not required that the watched filehandle be a
regular file. It is possible to watch anything that C<stat(2)> may be called
on, such as directories or other filesystem entities.


=head1 EVENTS

The following events are invoked, either using subclass methods or CODE
references in parameters.

=head2 on_dev_changed $new_dev, $old_dev

=head2 on_ino_changed $new_ino, $old_ino

=head2 ...

=head2 on_ctime_changed $new_ctime, $old_ctime

Invoked when each of the individual C<stat()> fields have changed. All the
C<stat()> fields are supported apart from C<blocks> and C<blksize>. Each is
passed the new and old values of the field.

=head2 on_devino_changed $new_stat, $old_stat

Invoked when either of the C<dev> or C<ino> fields have changed. It is passed
two L<File::stat> instances containing the complete old and new C<stat()>
fields. This can be used to observe when a named file is renamed; it will not
be observed to happen on opened filehandles.

=head2 on_stat_changed $new_stat, $old_stat

Invoked when any of the C<stat()> fields have changed. It is passed two
L<File::stat> instances containing the old and new C<stat()> fields.



The following named parameters may be passed to C<new> or C<configure>.

=head2 handle => IO

The opened filehandle to watch for C<stat()> changes if C<filename> is not

=head2 filename => STRING

Optional. If supplied, watches the named file rather than the filehandle given
in C<handle>. The file will be opened for reading and then watched for
renames. If the file is renamed, the new filename is opened and tracked
similarly after closing the previous file.

=head2 interval => NUM

Optional. The interval in seconds to poll the filehandle using C<stat(2)>
looking for size changes. A default of 2 seconds will be applied if not


sub _init
   my $self = shift;
   my ( $params ) = @_;

   $params->{interval} ||= 2;

   $self->SUPER::_init( $params );


sub configure
   my $self = shift;
   my %params = @_;

   if( exists $params{filename} ) {
      my $filename = delete $params{filename};
      $self->{filename} = $filename;
   elsif( exists $params{handle} ) {
      $self->{handle} = delete $params{handle};
      $self->{last_stat} = stat $self->{handle};

   foreach ( @STATS, "devino", "stat" ) {
      $self->{"on_${_}_changed"} = delete $params{"on_${_}_changed"} if exists $params{"on_${_}_changed"};

   $self->SUPER::configure( %params );

sub _add_to_loop
   my $self = shift;

   if( !defined $self->{filename} and !defined $self->{handle} ) {
      croak "IO::Async::File needs either a filename or a handle";

   return $self->SUPER::_add_to_loop( @_ );

sub _reopen_file
   my $self = shift;

   my $path = $self->{filename};

   open $self->{handle}, "<", $path or croak "Cannot open $path for reading - $!";

   $self->{last_stat} = stat $self->{handle};

sub on_tick
   my $self = shift;

   my $old = $self->{last_stat};
   my $new = stat( defined $self->{filename} ? $self->{filename} : $self->{handle} );

   my $any_changed;
   foreach my $stat ( @STATS ) {
      next if $old->$stat == $new->$stat;

      $self->maybe_invoke_event( "on_${stat}_changed", $new->$stat, $old->$stat );

   if( $old->dev != $new->dev or $old->ino != $new->ino ) {
      $self->maybe_invoke_event( on_devino_changed => $new, $old );

   if( $any_changed ) {
      $self->maybe_invoke_event( on_stat_changed => $new, $old );
      $self->{last_stat} = $new;

=head1 METHODS


=head2 handle

   $handle = $file->handle

Returns the filehandle currently associated with the instance; either the one
passed to the C<handle> parameter, or opened from the C<filename> parameter.


sub handle
   my $self = shift;
   return $self->{handle};

=head1 AUTHOR

Paul Evans <leonerd@leonerd.org.uk>