=begin pod

=TITLE class IO::Notification

=SUBTITLE Asynchronous notification for file and directory changes
X<|IO::Notification::Change>

=for code :skip-test
enum FileChangeEvent (:FileChanged(1), :FileRenamed(2));
=for code :skip-test
class IO::Notification  {
    class Change {
        has $.path;
        has $.event;
    }
    ...
}

C<IO::Notification.watch-path($path)> produces a L<Supply|/type/Supply> of
C<IO::Notification::Change> events for a file or directory.

Here is a small example that prints the first ten FileChanged-notifications for
the current working directory:

=for code :skip-test
my $finish = Promise.new;
my $count = 0;
IO::Notification.watch-path($*CWD).act( -> $change {
    $count++ if $change.event ~~ FileChanged;
    say "($count) $change.path(): $change.event()";
    $finish.keep if $count >= 10;
});
await $finish;

The type of the change is very much dependent both on the platform and on
specific system calls that were used initiate the change. At this point in time
you should not rely on the type of change in general, and test your particular
situation.

=head1 Methods

=head2 method watch-path

=for code :skip-test
method watch-path(IO::Notification: Str() $path, :$scheduler = $*SCHEDULER)

Returns a L<Supply|/type/Supply> that emits C<IO::Notification::Change> objects.

If C<$path> is a file, only modifications of that file are reported. If
C<$path> is a directory, both modifications to the directory itself (for
example permission changes) and to files in the directory (including new files
in the directory) are reported.

C<:$scheduler> allows you to specify which thread scheduler is responsible
for the notification stream.

=end pod
