From ec46722df8e61b07ec66ba7898c76a69f6b5ed8f Mon Sep 17 00:00:00 2001 From: Olof-Joachim Frahm Date: Thu, 9 Jun 2011 14:45:56 +0200 Subject: [PATCH] Added more description and markup. --- README | 78 ++++++++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 49 insertions(+), 29 deletions(-) diff --git a/README b/README index aff4efc..094cb71 100644 --- a/README +++ b/README @@ -4,64 +4,84 @@ Copyright (C) 2011 Olof-Joachim Frahm Released under a Simplified BSD license. Working, but unfinished. -Implementations currently tested on: SBCL. +Implementations currently running on: SBCL. -Uses CFFI, binary-types (from [1] or see [2]) and trivial-utf-8. +Uses CFFI, binary-types (from [my Github][1] or see [CLiki][2]) and +trivial-utf-8. Doesn't use iolib, because we don't need most of the +functionality, although it might gain us some implementation +independence (patches which can be conditionally compiled are welcome). -HOWTO +# HOWTO -After loading the library use MAKE-INOTIFY to create a new event queue. -The NONBLOCKING argument currently determines if we use the standard -CL:LISTEN function or SB-UNIX:UNIX-READ to check for available events. +After loading the library use `MAKE-INOTIFY` to create a new event +queue. The `NONBLOCKING` argument currently determines if we use the +standard `CL:LISTEN` function or `SB-UNIX:UNIX-READ` to check for +available events. -The result of MAKE-INOTIFY is used with WATCH and UNWATCH, the first +The result of `MAKE-INOTIFY` is used with `WATCH` and `UNWATCH`, the first being used to watch a file or directory, the second to stop watching -it. The FLAGS parameter of WATCH is described in the notify(7) manpage; -you can use a combination of the flags (as keywords) to create a -suitable bitmask. +it. The `FLAGS` parameter of `WATCH` is described in the notify(7) +manpage; you can use a combination of the flags (as keywords) to create +a suitable bitmask. The types `INOTIFY-ADD/READ-FLAG`, +`INOTIFY-READ-FLAG` and `INOTIFY-ADD-FLAG` are also defined and can be +examined. For example, to watch for modified or closed files in a directory, call -(WATCH inotify "foo/" '(:modify :close)). +`(WATCH inotify "foo/" '(:modify :close))`. -The result of WATCH is a handle (currently a FIXNUM, but I wouldn't rely -on that) which can be fed to UNWATCH and can be translated from events -with EVENT-PATHNAME/FLAGS. +The result of `WATCH` is a handle (currently a `FIXNUM`, but I wouldn't +rely on that) which can be fed to `UNWATCH` and can be translated from +events with `EVENT-PATHNAME/FLAGS`. -To finally get the events from the queue, use READ-EVENT (which blocks) -or NEXT-EVENT (which doesn't block). EVENT-AVAILABLEP does what it -should do, NEXT-EVENTS retrieves all currently available events as a -list and DO-EVENTS (nonblocking) iterates over available events. +To finally get the events from the queue, use `READ-EVENT` (which +blocks) or `NEXT-EVENT` (which doesn't block). `EVENT-AVAILABLEP` does +what it should do, `NEXT-EVENTS` retrieves all currently available +events as a list and `DO-EVENTS` (nonblocking) iterates over available +events. The enhanced API registers all watched paths in a hashtable, so you can -use PATHNAME-HANDLE/FLAGS to check if a pathname (exact match) is being -watched and LIST-WATCHED to return all watched paths as a list. -EVENT-PATHNAME/FLAGS may be used to get the pathname and flags for a +use `PATHNAME-HANDLE/FLAGS` to check if a pathname (exact match) is +being watched and `LIST-WATCHED` to return all watched paths as a list. +`EVENT-PATHNAME/FLAGS` may be used to get the pathname and flags for a read event. -UNWATCH has to be called with the path or the handle of the watched file -or directory (a path'll looked up in the same table as with WATCHEDP). +`UNWATCH` has to be called with the path or the handle of the watched +file or directory (a path will be looked up in the same table as with +`PATHNAME-HANDLE/FLAGS`). The raw API, which doesn't register watched paths, consists of -READ-RAW-EVENT-FROM-STREAM, READ-EVENT-FROM-STREAM, WATCH-RAW and -UNWATCH-RAW. They are just a thin wrapper around the C functions, but -I've exported them in case someone doesn't like the upper layers. +`READ-RAW-EVENT-FROM-STREAM`, `READ-EVENT-FROM-STREAM`, `WATCH-RAW` and +`UNWATCH-RAW`. They are just a thin wrapper around the C functions, but +they're exported in case someone doesn't like the upper layers. -TODO +# EXAMPLE + + > (use-package '#:cl-inotify) + > (defvar *tmp*) + > (setf *tmp* (make-notify)) + > (watch *tmp* "/var/tmp/" :all-events) + > (next-events *tmp*) + > (close-inotify *tmp*) + + +# TODO - more functionality to examine read events - extend to other APIs? - make things more implementation independent - (maybe) don't use the libc for this, direct syscall +- (maybe) add iolib replacement for io functions + +# DONE -DONE - easier interface for (e)poll/select maybe using iolib (done, using CL:LISTEN and/or SB-UNIX:UNIX-READ) LINKS -[1]: http://github.com/Ferada/cl-notify +[1]: https://github.com/Ferada/binary-types [2]: http://www.cliki.net/Binary-types -- 1.7.10.4