Watch (gb.inotify)

This class represents a monitored filesystem object.

Inotify events are reported asynchronously and the kernel makes no guarantees to deliver events in a timely manner. If for example a file is created and then immediately deleted in a directory you watch, it can happen that you get the Create event after the file is already deleted. If you are not careful and try to read the file named by Watch.Name, your program will crash with "No such file or directory".

You should read the "Limitations and caveats" section of the inotify manpage (man 7 inotify). This same manpage is a good source for additional information.

Watching a directory is NOT recursive, i.e. you will only receive events from the directory itself and its immediate entries. If you want to go deeper, you must add recursive watches manually.

This class is creatable.

Constants
All   Watch all events.
Close   Watch for the Close event.
Create   Watch for the Create event.
Delete   Watch for the Delete event.
Move   Watch for the Move event.
MoveFrom   Watch for the MoveFrom event.
MoveTo   Watch for the MoveTo event.
Open   Watch for the Open event.
Read   Watch for the Read event.
Stat   Watch for the Stat event.
Write   Watch for the Write event.

Static properties
Cookie   A cookie used to associate events. This is currently only used to connect MoveFrom and MoveTo events of the same file.
IsDir   Return whether the event subject is/was a directory.
Name   The name of the file or directory which is subject to the event, relative to the Watch object which triggered the event. If Null, the directory itself is subject.
Unmount   Return whether the filesystem on which the watched path resided, was unmounted. In this case, the Watch object is invalidated just after the event.

Properties
Events   Return a virtual class to specify the event monitoring bitmask.
IsPaused   Returns if the watch is paused.
Path   Return the watched path.
Tag   This Variant is free for use by the Gambas programmer.

Methods
Pause   Pauses the watch, i.e. disables event generation.
Resume   Resumes the watch if it was paused.

Events
Close   This event is raised when the watched file or a file in the watched directory is closed.
Create   This event is raised when a file or directory was created in the watched directory.
Delete   This event is raised when an entry was deleted from the watched directory or the path itself was deleted.
Move   This event is raised when the watched file or directory was moved.
MoveFrom   This event is raised for the source directory when a file is being moved.
MoveTo   This event is raised for the destination directory when a file is being moved.
Open   This event is raised when the watched file or an entry in the watched directory was opened.
Read   This event is raised when the watched file or entry in the watched directory was accessed, i.e. read, executed, ....
Stat   This event is raised when file attributes/meta data changes. From $ man 7 inotify:
Write   This event is raised when the watched file or entry in the watched directory was modified, i.e. written to, truncated, ....

The static properties are used to store data from the kernel during event management. Use them only in event handlers.

Example

Use "gb.inotify"
'The above line is required for Gambas Script only, in full Gambas IDE, see Project Components.

Private $hWatch As Watch

Public Sub Main()
  Dim sFile1 As String = Temp$(), sFile2 As String = Temp$()

  $hWatch = New Watch(File.Dir(Temp$()), True) As "Watcher"

  ' This line is redundant: a Watch object will automatically subscribe to events for which an event handler exists!
  '$hWatch.Events[Watch.Create Or Watch.Delete] = True
  Print "I'm watching... "

  ' Create two files
  File.Save(sFile1, "abc")
  File.Save(sFile2, "def")
  Wait 0.1 ' enter event loop to see events

  ' Delete one file
  Kill sFile2
  Wait 0.1

  ' Delete the second file. The Delete event was unsubscribed at this point (see Watcher_Delete), so no event is raised for this.
  Kill sFile1
  Wait 1

  Quit
End

Public Sub Watcher_Create()
  Print "Create: " & Watch.Name
End

Public Sub Watcher_Delete()
  Print "Delete: " & Watch.Name
  ' Unsubscribe from deletions after the first one.
  Last.Events[Watch.Delete] = False
End
I'm watching...
Create: 1.tmp
Create: 2.tmp
Delete: 2.tmp