Chapter 3

fam-task reference

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-path⁴. 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.