Chapter 4

Low-level interface

4.1  Basics

Although fam-task does its very best to offer you an appealing interface, chances are some of you will find it unsuitable or simply dislike it. Besides telling me what you'd like to see in fam-task, you can use the low-level monitoring API described in this chapter as an alternative. This API, defined as a set of generic procedures exported by the fam-base, is a more or less direct translation of the C interface provided by libfam, and is implemented by the fam module using PLT's FFI and by the fam-mz module using pure Scheme. Each of the latter modules provides a constructor (make-fam and make-mz-fam) that returns a FAM connection object to be used as the first argument of every generic procedure.

So, the general idea is that you pick an underlying implementation and require it together with fam-base, and happily proceed to use it:

(require "fam-base.ss" (planet "jao" "mzfam.plt" 1 0))

(require "fam.ss" (planet "jao" "mzfam.plt" 1 0)) ;; or "fam-mz.ss"

(define fc (make-fam)) ;; or (make-mz-fam)
;; ... use fc via fam-base's generic functions ...

In addition, fam-base exports all bindings in Swindle, so that your implementation can take advantage of this fine CLOS clone, if you feel like that. That's, by the way, the reason I keep calling the procedures exported by fam-base generic: they're actually implemented as generic functions. FAM events are instances of a Swindle class, <fam-event>, which is also exported for your convenience.

The next section gives you all the details you need to know in order to use fam-base's interface. Note that you can also look at this interface from below, that is, as a provider of a new native implementation of FAM primitives (Windows anyone?). To wear this hat, you'll have to create you own FAM connection type and provide a constructor and concrete method implementation for the generics below. In exchange, you'll get FAM tasks based on your new implementation for free.

4.2  Generic low-level interface

As stated in the previous section, all procedures below take as first argument a FAM connection object created with either make-fam (from fam) or make-mz-fam (from fam-mz).

• (fam-monitor-path fc path) adds path (a string) to the set of paths monitored by fc.

• (fam-monitored-paths fc) returns the list of (absolute) paths currently monitored by fc.

• (fam-suspend-path-monitoring fc path)/fam-resume-path-monitoring fc path suspends (resumes) monitoring of the given path. Events occurring during suspension are remembered.

• (fam-cancel-path-monitoring fc path) removes path from the list of monitored paths.

• (fam-any-event? fc) tests whether there are pending events.

• (fam-next-event fc [wait]) grabs the next available event (an instance of <fam-event>). If the optional parameter wait is #t, the call blocks until an event is available (the default is a non-blocking call).

• (fam-pending-events fc) returns a list of all available events. This procedure is always non-blocking.

In addition, fam-base exports the FAM event selectors and the auxiliar procedure fam-event-type->string described at the end of section 3. These procedures are actually implemented by fam-base, unlike the generic functions above.