/ 
Linux-Event-0.117
/ Linux::Event::Kernel::Inotify::Event

NAME

Linux::Event::Kernel::Inotify::Event - Describe one filesystem notification

SYNOPSIS

on_create => sub ($event) {
    say "created: " . $event->path;

    if ($event->is_directory) {
        say "it is a directory";
    }
}

DESCRIPTION

Linux::Event::Kernel::Inotify::Event is the value object passed to Inotify watch callbacks.

Applications do not construct Event objects directly.

Linux::Event creates one when the kernel reports a filesystem notification.

For example:

my $watch = $inotify->watch(
    '/srv/uploads',

    on_create => sub ($event) {
        say $event->path;
    },
);

The Event tells the callback:

  • which logical Watch received the notification

  • which child name Linux reported, when applicable

  • the useful full path

  • the raw Linux event mask

  • the rename or move cookie

  • whether the event refers to a directory

THE SAME EVENT MAY REACH SEVERAL CALLBACKS

One Linux inotify record may contain several matching event bits.

For one logical Watch, Linux::Event creates one Event object for that record and passes the same object to each matching specific callback.

For example:

my $watch = $inotify->watch(
    '/srv/data',

    on_modify => sub ($event) {
        ...
    },

    on_event => sub ($event) {
        ...
    },
);

If one record matches on_modify, the same Event object is first passed to on_modify and then to on_event.

WATCH

watch

my $watch = $event->watch;

Return the Linux::Event::Kernel::Inotify::Watch that received this event.

This is useful when one callback is shared by several Watches:

my $callback = sub ($event) {
    say "watching: " . $event->watch->path;
    say "event:    " . $event->path;
};

CHILD NAME

name

my $name = $event->name;

Return the optional child name supplied by Linux.

For events on entries inside a watched directory, this is typically the directory entry name.

For example, if the Watch is:

/srv/uploads

and Linux reports activity for:

photo.jpg

then:

$event->name

returns:

photo.jpg

For events concerning the watched object itself, there may be no child name.

PATH

path

my $path = $event->path;

Return the useful composed path for the event.

When Linux supplies a child name, path combines the Watch path and that name.

For example:

watch path:  /srv/uploads
event name:  photo.jpg
event path:  /srv/uploads/photo.jpg

When Linux supplies no child name, path is simply the original Watch path.

This is usually the most convenient Event method for application code.

MASK

mask

my $mask = $event->mask;

Return the raw Linux inotify mask for this kernel record.

Most applications should prefer the named callbacks such as:

on_create
on_modify
on_delete
on_moved_from
on_moved_to

instead of decoding the raw mask themselves.

mask is available for applications that need lower-level Linux event information or diagnostic output.

For example:

on_event => sub ($event) {
    say "mask=" . $event->mask;
}

MOVE AND RENAME COOKIE

my $cookie = $event->cookie;

Return the Linux inotify cookie associated with this record.

The cookie is primarily useful for pairing related move or rename events.

For example:

on_moved_from => sub ($event) {
    remember_old_name(
        $event->cookie,
        $event->path,
    );
}

on_moved_to => sub ($event) {
    complete_rename(
        $event->cookie,
        $event->path,
    );
}

Linux commonly gives the related IN_MOVED_FROM and IN_MOVED_TO records the same nonzero cookie.

Applications that do not need to correlate renames can usually ignore this field.

DIRECTORY FLAG

is_directory

if ($event->is_directory) {
    ...
}

Return true when the Linux event mask contains IN_ISDIR.

For example:

on_create => sub ($event) {
    if ($event->is_directory) {
        say "directory created: " . $event->path;
    }
    else {
        say "file created: " . $event->path;
    }
}

This reports what Linux marked on the event.

It does not perform a new filesystem stat call.

EVENT VALUES ARE SNAPSHOTS

An Event describes the notification that Linux delivered at that moment.

The filesystem may change again immediately afterward.

For example, by the time this callback runs:

on_create => sub ($event) {
    ...
}

the path could already have been renamed or deleted by another process.

Therefore the Event should be treated as a record of what Linux reported, not as a guarantee that the path still has the same current filesystem state.

Applications that need current metadata should query the filesystem separately.

EVENT OBJECTS DO NOT CONTROL THE WATCH

An Event is descriptive.

Lifecycle operations belong to the Watch or parent Inotify object.

To cancel the logical subscription from a callback:

on_modify => sub ($event) {
    $event->watch->cancel;
}

To close the whole inotify service:

on_modify => sub ($event) {
    $event->watch->inotify->close;
}

IMMUTABILITY

The public Event API provides only readers:

watch
name
path
mask
cookie
is_directory

There are no public setters.

An Event represents one already-observed kernel notification and is intended to be treated as an immutable value.

SEE ALSO

Linux::Event, Linux::Event::Loop, Linux::Event::Kernel::Inotify, Linux::Event::Kernel::Inotify::Watch.