As promised, here’s a list of all procedures provided by
fam-task, together with their (informal) contracts.
(fam-task-create {period event-handler}) creates a new
fam-task instance. The two optional arguments can be provided
in any order; period denotes the time (in seconds) the polling
thread sleeps (default value is 0.1, given by the parameter
fam-task-default-period), while event-handler (a
procedure of arity one) is the default event handler. Returns a new
fam-task or #f in case of error. If the period is 0 and
the native implementation is used, the task will block (after
started) while there are no events.
(fam-task-start fam-task) starts a given task, evaluating
to a boolean indicating whether the operation is successful. The
value of the parameter fam-use-native? is used to decide
whether the FAM- or the Scheme-based monitoring implementation is
used.
(fam-task-join fam-task) calls fam-task-start and, if
successful, waits on the monitoring thread to exit.
(fam-task-stop fam-task) sends a message to a running FAM
task, causing it exit the monitoring thread. Thus, a certain delay
until the task actually exits is to be expected (especially for
blocking tasks). Returns a boolean success flag.
(fam-task-running? fam-task) check whether a monitoring
task’s thread is running.
(fam-task-add-path fam-task path [handler] [evlist]
[rec-level]) adds given path to the list of monitored ones.
It takes the following optional arguments (use #f to denote
their default value):
handler (default is #t, indicating the handler
provided when creating fam-task) must be a procedure of
arity 1 (it will be called with an event as its argument).
evlist is a list of symbols corresponding to the types
of events that should be reported (see
section 2.3.1 for possible values). If #f
(the default) all event types are reported.
rec-level is used only when path denotes a
directory, and indicates the level for recursively monitoring
subdirectories of path. 0 or #f (the default) denote
no recursion, and #t always recurse. Otherwise,
subdirectories inherit a recursion level which is one less than
their parent (see also discussion in
section 2.2.2).
Returns a boolean success flag.
(fam-task-remove-path fam-task path) removes path
from the list of monitored paths. path must correspond to a
pathname added using fam-task-add-path1. Returns a boolean success flag.
(fam-task-suspend-monitoring fam-task path) temporarily
delays event notifications for the given path (a previous argument
to fam-task-add-path, with the same caveats as
fam-task-remove-path). When monitoring is resumed, events
collected during the lapse are reported. Returns a boolean success
flag.
(fam-task-resume-monitoring fam-task path) resumes a
previously suspended path. Returns a boolean success flag.
(fam-task-monitored-paths fam-task) evaluates to a list of
strings, corresponding to the currently monitored paths (including
suspended ones).
fam-task-default-period is a parameter providing the default
sleep period (in seconds; non-integer values allowed) for
fam-task-create (initially set to 0.1 secs).
Event handlers get passed an argument of type fam-event, an
opaque structure whose contents can be inspected with the following
selectors:
(fam-event-path fam-event) provides the file that has been
altered (a string representing an absolute pathname).
(fam-event-type fam-event) returns one of the symbols listed in
section 2.3.1.
(fam-event-monitored-path fam-event) returns the path being
monitored (a string representing an absolute pathname). This may be
different from the value returned by fam-event-path when
monitoring directories.
(fam-event-timestamp fam-event) evaluates to the last
modification time of the file given by fam-event-path.
(fam-event-type->string type) returns a string with a
boilerplate description (in English) of the given event type.
(fam-make-event-stream) creates a procedure that doubles as
an event handler (to be uses as an argument to fam-task-create
or fam-task-add-path) and as a synchronous event reader. When
called with an event as argument (usually by the framework), the
event is queued. Events can be retrieved by calling the procedure
either without arguments (non-blocking call) or #t (blocks
until events are available in the queue). See
section 2.3.2 for usage examples.
Finally, you can control to some extend the underlying machinery used by FAM tasks to detect events:
fam-use-native? is a boolean parameter that controls the
underlying implementation used by FAM tasks. Its initial value is
set to #t if a FAM/Gamin process can be connected. Otherwise,
its value is #f, meaning that the fall-back pure-scheme
implementation is in use (see section 2.2.1
for caveats). Alternative, you can set it yourself to force a
concrete behaviour. Note that this parameter is used when the task
starts; thus, if you are using it in a parameterize form, this
form should wrap your calls to either fam-task-start of
fam-task-join.
1 That is, this function will not work for paths of regular files inside monitored directories, nor for subdirectories when recursive monitoring is off. The same caveat applies to suspend/resume below.