Chapter 1

Introduction

MzFAM consists of a set of PLT-scheme modules providing utilities to monitor and react to filesystem changes. It exports a high-level interface consisting of monitoring tasks that run as independent threads and invoke callback procedures each time a file alteration is detected. These high-level tasks (provided by the module fam-task) are implemented using either Linux's FAM/Gamin monitors or, in systems (like Windows) where it is not available, a pure Scheme fall-back implementation. This low-level functionality is in turn provided by two modules (fam and fam-mz, respectively) that share the generic interface defined by a third one, fam-base. You may use fam or fam-mz directly (bypassing the high-level interface) if you find fam-task not suitable for your needs. The generic functions in fam-base are, basically, one-to-one counterparts of those provided by the libfam C library¹.

Using FAM tasks is quite straightforward. So, the impatient among you may prefer to take a look at the procedures exported by fam-task.ss (and perhaps the sample scripts in the aptly named examples subdirectory) and skip the rest of this manual. For those of you still here, chapter 2 is a tutorial on FAM tasks, and should provide all the information needed to use MzFAM in your programs. In chapter 3, you'll find reference sections (written using the dry, legalistic tone we all know and love) with all the details of the exported fam-task interface.

In case you need more fine-grained control over your file-monitoring, turn to chapter 4, which describes the generic interface exported by the fam-base module and implemented by fam (using libfam (or libgamin)) and by fam-mz (using Scheme).

1.1  Getting MzFAM

The latest MzFAM stable release is available on PLaneT, where you can also browse the source code and documentation. As with any other PLaneT-enabled package, using a require line like this one

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

anywhere in your program will trigger the network magic necessary to get MzFAM installed in your system.

If you feel like living on the bleeding edge, the development tree (which includes build scripts and the documentation sources) can also be browsed online, and you can get it using darcs:

    darcs get http://hacks-galore.org/jao/darcs/mzfam

Needless to say, you're not only welcome, but actually encouraged to send the author bug reports, improvement suggestions, constructive criticism or any kind of undeserved praise.