The cl-fam Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-fam Reference Manual

This is the cl-fam Reference Manual, version 1.0, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 08:00:47 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

#LINUX DEPENDENCIES

Requires either fam or gamin, and corresponding development package (for /usr/include/fam.h). It seem that gamin is a better choice, because it uses inotify facility in modern kernels.

#SYNOPSIS

(ql:quickload :cl-fam)

(cl-fam:fam-open)

(cl-fam:fam-monitor-directory "/tmp")

;; #<CL-FAM::FAM-DIRECTORY-REQUEST {10201EC243}>

(loop while (cl-fam:fam-pending-p)
      collect (multiple-value-list (cl-fam:fam-next-event t)))

;; ((:FAM-EXISTS "wfsnp" #<CL-FAM::FAM-DIRECTORY-REQUEST {10201EC243}>)
;; (:FAM-EXISTS ".tmp18421" #<CL-FAM::FAM-DIRECTORY-REQUEST {10201EC243}>)
;; (:FAM-EXISTS "ztjvq" #<CL-FAM::FAM-DIRECTORY-REQUEST {10201EC243}>)

;; touch some files in /tmp

;; FAM-NEXT-EVENT returns FAM-EVENT object by default

(loop while (cl-fam:fam-pending-p)
      as event = (cl-fam:fam-next-event)
      collect (cons (cl-fam:fam-code event)
                    (cl-fam:fam-filename event)))

;; ((:FAM-EXISTS "wghpa"))

;; Multiple monitoring requests can run at the same time, they can be
;; distinguished by the request object returned by the
;; FAM-MONITOR-FILE/DIRECTORY functions. Each connection has a file
;; descriptor which can be used in select/poll, to integrate event
;; monitoring into multiple wait scenarios

(cl-fam:fam-fd)
;; 6

For more full description of the API see http://www.docunext.com/wiki/Gamin

See docstrings for exported functions for more info.

If you want to try it out with multiple threads, bind CL-FAM:*FAM* in the thread, this way the FAM connection would be open per-thread.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-fam

Author

Max Mikhanosha <max@openchat.com>

License

Apache

Description

Wraps libfam (File access monitor) API. Needs gamin-devel or fam-devel package

Version

1.0

Defsystem Dependency

cffi-grovel

Dependencies
Source

cl-fam.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-fam.asd

Location

cl-fam.asd

Systems

cl-fam (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-fam/package.lisp

Parent

cl-fam (system)

Location

package.lisp

Packages

cl-fam


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-fam/fam-grovel.lisp

Dependency

package.lisp (file)

Parent

cl-fam (system)

Location

fam-grovel.lisp


Previous: , Up: Lisp files   [Contents][Index]

3.1.4 cl-fam/cl-fam.lisp

Dependency

fam-grovel.lisp (file)

Parent

cl-fam (system)

Location

cl-fam.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-fam

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *fam*

Current FAM connection

Package

cl-fam

Source

cl-fam.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: fam-cancel-monitor REQ

Cancel monitoring request.

Package

cl-fam

Source

cl-fam.lisp (file)

Function: fam-close &optional CONN

Close the FAM connection

Package

cl-fam

Source

cl-fam.lisp (file)

Function: fam-fd &optional CONN

Return FAM file handle

Package

cl-fam

Source

cl-fam.lisp (file)

Function: fam-init &optional APP-NAME

Open default FAM connection if its not already opened, same as (FAM-OPEN app-name T)

Package

cl-fam

Source

cl-fam.lisp (file)

Function: fam-monitor-directory FILENAME &optional CONN FORCE-DUP

Monitor directory for changes. Returns FAM-DIRECTORY-REQUEST object, which can be used to cancel or suspend the request. The same request object will be returned as a slot of FAM-NEXT-EVENT.

In case the directory is already being monitored, return the existing request rather then starting a new one, unless FORCE-DUP is also specified.

The second returned value will be T if new request was created

Package

cl-fam

Source

cl-fam.lisp (file)

Function: fam-monitor-file FILENAME &optional CONN FORCE-DUP

Monitor file for changes. Returns FAM-FILE-REQUEST object, which can be used to cancel or suspend the request. The same request object will be returned as a slot of FAM-NEXT-EVENT.

In case the directory is already being monitored, return the existing request rather then starting a new one, unless FORCE-DUP is also specified.

The second returned value will be T if new request was created

Package

cl-fam

Source

cl-fam.lisp (file)

Function: fam-next-event &optional USE-VALUES CONN

Return queued FAM event from the specified connection, if no events are pending will wait for one. By default the event is returned as an instance of FAM-EVENT class.

The FAM-CODE is translated into the keyword,

With USE-VALUES flag returns event code, filename and FAM-REQUEST object as three values.

Package

cl-fam

Source

cl-fam.lisp (file)

Function: fam-open &optional APP-NAME REUSE

Optionally open new FAM connection and return it.

With REUSE flag return default connection if its open, or create a new connection and make it default. Default connection is stored in *FAM* special variable.

Without REUSE flag, unconditionally create new connection, and return it without storing it in *FAM*.

Package

cl-fam

Source

cl-fam.lisp (file)

Function: fam-open-p &optional CONN

Return T if connection is open

Package

cl-fam

Source

cl-fam.lisp (file)

Function: fam-pending-p &optional CONN

Return number of events pending on FAM connection or NIL if none are.

Package

cl-fam

Source

cl-fam.lisp (file)

Function: fam-requests &optional CONN

Return all the active requests for the connection

Package

cl-fam

Source

cl-fam.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Generic functions

Generic Function: fam-code OBJECT
Package

cl-fam

Methods
Method: fam-code (FAM-EVENT fam-event)

automatically generated reader method

Source

cl-fam.lisp (file)

Generic Function: fam-connection OBJECT
Package

cl-fam

Methods
Method: fam-connection (FAM-EVENT fam-event)

automatically generated reader method

Source

cl-fam.lisp (file)

Method: fam-connection (FAM-REQUEST fam-request)

automatically generated reader method

Source

cl-fam.lisp (file)

Generic Function: fam-filename OBJECT
Package

cl-fam

Methods
Method: fam-filename (FAM-EVENT fam-event)

automatically generated reader method

Source

cl-fam.lisp (file)

Method: fam-filename (FAM-REQUEST fam-request)

automatically generated reader method

Source

cl-fam.lisp (file)

Generic Function: fam-hostname OBJECT
Package

cl-fam

Methods
Method: fam-hostname (FAM-EVENT fam-event)

automatically generated reader method

Source

cl-fam.lisp (file)

Generic Function: fam-request OBJECT
Package

cl-fam

Methods
Method: fam-request (FAM-EVENT fam-event)

automatically generated reader method

Source

cl-fam.lisp (file)

Generic Function: fam-request-number OBJECT
Package

cl-fam

Methods
Method: fam-request-number (FAM-REQUEST fam-request)

automatically generated reader method

Source

cl-fam.lisp (file)

Generic Function: fam-status OBJECT
Package

cl-fam

Methods
Method: fam-status (FAM-REQUEST fam-request)

automatically generated reader method

Source

cl-fam.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Classes

Class: fam-connection ()

Stores information about FAM connection. If garbage collected then C level FAM connection will be automatically closed

Package

cl-fam

Source

cl-fam.lisp (file)

Direct superclasses

standard-object (class)

Direct slots
Slot: %connection
Type

cffi-sys:foreign-pointer

Initargs

:connection

Slot: requests
Initform

(make-hash-table)

Slot: fd
Type

integer

Initargs

:fd

Slot: %open-flag
Initform

(list t)

Class: fam-request ()

Base class for FAM request

Package

cl-fam

Source

cl-fam.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses
Direct methods
Direct slots
Slot: request-number
Initargs

:request-number

Readers

fam-request-number (generic function)

Slot: filename
Initargs

:filename

Readers

fam-filename (generic function)

Slot: connection
Type

cl-fam:fam-connection

Initargs

:connection

Readers

fam-connection (generic function)

Slot: status
Readers

fam-status (generic function)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Constants

Constant: size-of-famconnection
Package

cl-fam

Source

/home/quickbuilder/.cache/common-lisp/sbcl-1.4.0-linux-x64/home/quickbuilder/quicklisp/dists/quicklisp/software/cl-fam-20121125-git/fam-grovel.processed-grovel-file

Constant: size-of-famevent
Package

cl-fam

Source

/home/quickbuilder/.cache/common-lisp/sbcl-1.4.0-linux-x64/home/quickbuilder/quicklisp/dists/quicklisp/software/cl-fam-20121125-git/fam-grovel.processed-grovel-file

Constant: size-of-famrequest
Package

cl-fam

Source

/home/quickbuilder/.cache/common-lisp/sbcl-1.4.0-linux-x64/home/quickbuilder/quicklisp/dists/quicklisp/software/cl-fam-20121125-git/fam-grovel.processed-grovel-file


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Symbol macros

Symbol Macro: %fam-errno
Package

cl-fam

Source

cl-fam.lisp (file)

Expansion

(cl-fam::%var-accessor-%fam-errno)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: %fam-cancel-monitor CONN REQ
Package

cl-fam

Source

cl-fam.lisp (file)

Function: %fam-close CONN
Package

cl-fam

Source

cl-fam.lisp (file)

Function: %fam-monitor-directory CONN FILENAME REQ USERDATA
Package

cl-fam

Source

cl-fam.lisp (file)

Function: %fam-monitor-file CONN FILENAME REQ USERDATA
Package

cl-fam

Source

cl-fam.lisp (file)

Function: %fam-next-event CONN FA
Package

cl-fam

Source

cl-fam.lisp (file)

Function: %fam-open-2 CONN APP-NAME
Package

cl-fam

Source

cl-fam.lisp (file)

Function: %fam-pending CONN
Package

cl-fam

Source

cl-fam.lisp (file)

Function: %fam-resume-monitor CONN REQ
Package

cl-fam

Source

cl-fam.lisp (file)

Function: %fam-suspend-monitor CONN REQ
Package

cl-fam

Source

cl-fam.lisp (file)

Function: %var-accessor-%fam-errno ()
Function: (setf %var-accessor-%fam-errno) VALUE
Package

cl-fam

Source

cl-fam.lisp (file)

Function: check-connection CONN

Throw error unless connection is non-NIL and open

Package

cl-fam

Source

cl-fam.lisp (file)

Function: fam-monitor-any KIND FILENAME &optional CONN FORCE-DUP

Common code for FAM-MONITOR-DIRECTORY and FAM-MONITOR-FILE

Package

cl-fam

Source

cl-fam.lisp (file)

Function: fam-resume-monitor REQ

Resume monitoring request.

Package

cl-fam

Source

cl-fam.lisp (file)

Function: fam-suspend-monitor REQ

Suspend monitoring request.

Package

cl-fam

Source

cl-fam.lisp (file)

Function: translate-fam-code CODE

Return FAM keyword for code

Package

cl-fam

Source

cl-fam.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Classes

Class: fam-directory-request ()

FAM request to monitor a directory

Package

cl-fam

Source

cl-fam.lisp (file)

Direct superclasses

fam-request (class)

Class: fam-event ()

Contains information about FAM event, is returned by FAM-NEXT-EVENT

Package

cl-fam

Source

cl-fam.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: hostname
Initargs

:hostname

Readers

fam-hostname (generic function)

Slot: filename
Initargs

:filename

Readers

fam-filename (generic function)

Slot: code
Initargs

:code

Readers

fam-code (generic function)

Slot: request
Type

cl-fam:fam-request

Initargs

:request

Readers

fam-request (generic function)

Slot: connection
Type

cl-fam:fam-connection

Initargs

:connection

Readers

fam-connection (generic function)

Class: fam-file-request ()

FAM request to monitor a file

Package

cl-fam

Source

cl-fam.lisp (file)

Direct superclasses

fam-request (class)

Class: famconnection-tclass ()
Package

cl-fam

Source

/home/quickbuilder/.cache/common-lisp/sbcl-1.4.0-linux-x64/home/quickbuilder/quicklisp/dists/quicklisp/software/cl-fam-20121125-git/fam-grovel.processed-grovel-file

Direct superclasses
  • translatable-foreign-type (class)
  • foreign-struct-type (class)
Class: famevent-tclass ()
Package

cl-fam

Source

/home/quickbuilder/.cache/common-lisp/sbcl-1.4.0-linux-x64/home/quickbuilder/quicklisp/dists/quicklisp/software/cl-fam-20121125-git/fam-grovel.processed-grovel-file

Direct superclasses
  • translatable-foreign-type (class)
  • foreign-struct-type (class)
Class: famrequest-tclass ()
Package

cl-fam

Source

/home/quickbuilder/.cache/common-lisp/sbcl-1.4.0-linux-x64/home/quickbuilder/quicklisp/dists/quicklisp/software/cl-fam-20121125-git/fam-grovel.processed-grovel-file

Direct superclasses
  • translatable-foreign-type (class)
  • foreign-struct-type (class)

Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-fam.asd: The cl-fam<dot>asd file
cl-fam/cl-fam.lisp: The cl-fam/cl-fam<dot>lisp file
cl-fam/fam-grovel.lisp: The cl-fam/fam-grovel<dot>lisp file
cl-fam/package.lisp: The cl-fam/package<dot>lisp file

F
File, Lisp, cl-fam.asd: The cl-fam<dot>asd file
File, Lisp, cl-fam/cl-fam.lisp: The cl-fam/cl-fam<dot>lisp file
File, Lisp, cl-fam/fam-grovel.lisp: The cl-fam/fam-grovel<dot>lisp file
File, Lisp, cl-fam/package.lisp: The cl-fam/package<dot>lisp file

L
Lisp File, cl-fam.asd: The cl-fam<dot>asd file
Lisp File, cl-fam/cl-fam.lisp: The cl-fam/cl-fam<dot>lisp file
Lisp File, cl-fam/fam-grovel.lisp: The cl-fam/fam-grovel<dot>lisp file
Lisp File, cl-fam/package.lisp: The cl-fam/package<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   (  
C   F   G   M   T  
Index Entry  Section

%
%fam-cancel-monitor: Internal functions
%fam-close: Internal functions
%fam-monitor-directory: Internal functions
%fam-monitor-file: Internal functions
%fam-next-event: Internal functions
%fam-open-2: Internal functions
%fam-pending: Internal functions
%fam-resume-monitor: Internal functions
%fam-suspend-monitor: Internal functions
%var-accessor-%fam-errno: Internal functions

(
(setf %var-accessor-%fam-errno): Internal functions

C
check-connection: Internal functions

F
fam-cancel-monitor: Exported functions
fam-close: Exported functions
fam-code: Exported generic functions
fam-code: Exported generic functions
fam-connection: Exported generic functions
fam-connection: Exported generic functions
fam-connection: Exported generic functions
fam-fd: Exported functions
fam-filename: Exported generic functions
fam-filename: Exported generic functions
fam-filename: Exported generic functions
fam-hostname: Exported generic functions
fam-hostname: Exported generic functions
fam-init: Exported functions
fam-monitor-any: Internal functions
fam-monitor-directory: Exported functions
fam-monitor-file: Exported functions
fam-next-event: Exported functions
fam-open: Exported functions
fam-open-p: Exported functions
fam-pending-p: Exported functions
fam-request: Exported generic functions
fam-request: Exported generic functions
fam-request-number: Exported generic functions
fam-request-number: Exported generic functions
fam-requests: Exported functions
fam-resume-monitor: Internal functions
fam-status: Exported generic functions
fam-status: Exported generic functions
fam-suspend-monitor: Internal functions
Function, %fam-cancel-monitor: Internal functions
Function, %fam-close: Internal functions
Function, %fam-monitor-directory: Internal functions
Function, %fam-monitor-file: Internal functions
Function, %fam-next-event: Internal functions
Function, %fam-open-2: Internal functions
Function, %fam-pending: Internal functions
Function, %fam-resume-monitor: Internal functions
Function, %fam-suspend-monitor: Internal functions
Function, %var-accessor-%fam-errno: Internal functions
Function, (setf %var-accessor-%fam-errno): Internal functions
Function, check-connection: Internal functions
Function, fam-cancel-monitor: Exported functions
Function, fam-close: Exported functions
Function, fam-fd: Exported functions
Function, fam-init: Exported functions
Function, fam-monitor-any: Internal functions
Function, fam-monitor-directory: Exported functions
Function, fam-monitor-file: Exported functions
Function, fam-next-event: Exported functions
Function, fam-open: Exported functions
Function, fam-open-p: Exported functions
Function, fam-pending-p: Exported functions
Function, fam-requests: Exported functions
Function, fam-resume-monitor: Internal functions
Function, fam-suspend-monitor: Internal functions
Function, translate-fam-code: Internal functions

G
Generic Function, fam-code: Exported generic functions
Generic Function, fam-connection: Exported generic functions
Generic Function, fam-filename: Exported generic functions
Generic Function, fam-hostname: Exported generic functions
Generic Function, fam-request: Exported generic functions
Generic Function, fam-request-number: Exported generic functions
Generic Function, fam-status: Exported generic functions

M
Method, fam-code: Exported generic functions
Method, fam-connection: Exported generic functions
Method, fam-connection: Exported generic functions
Method, fam-filename: Exported generic functions
Method, fam-filename: Exported generic functions
Method, fam-hostname: Exported generic functions
Method, fam-request: Exported generic functions
Method, fam-request-number: Exported generic functions
Method, fam-status: Exported generic functions

T
translate-fam-code: Internal functions

Jump to:   %   (  
C   F   G   M   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   %   *  
C   F   H   R   S  
Index Entry  Section

%
%connection: Exported classes
%fam-errno: Internal symbol macros
%open-flag: Exported classes

*
*fam*: Exported special variables

C
code: Internal classes
connection: Exported classes
connection: Internal classes
Constant, size-of-famconnection: Internal constants
Constant, size-of-famevent: Internal constants
Constant, size-of-famrequest: Internal constants

F
fd: Exported classes
filename: Exported classes
filename: Internal classes

H
hostname: Internal classes

R
request: Internal classes
request-number: Exported classes
requests: Exported classes

S
size-of-famconnection: Internal constants
size-of-famevent: Internal constants
size-of-famrequest: Internal constants
Slot, %connection: Exported classes
Slot, %open-flag: Exported classes
Slot, code: Internal classes
Slot, connection: Exported classes
Slot, connection: Internal classes
Slot, fd: Exported classes
Slot, filename: Exported classes
Slot, filename: Internal classes
Slot, hostname: Internal classes
Slot, request: Internal classes
Slot, request-number: Exported classes
Slot, requests: Exported classes
Slot, status: Exported classes
Special Variable, *fam*: Exported special variables
status: Exported classes
Symbol Macro, %fam-errno: Internal symbol macros

Jump to:   %   *  
C   F   H   R   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   F   P   S  
Index Entry  Section

C
cl-fam: The cl-fam system
cl-fam: The cl-fam package
Class, fam-connection: Exported classes
Class, fam-directory-request: Internal classes
Class, fam-event: Internal classes
Class, fam-file-request: Internal classes
Class, fam-request: Exported classes
Class, famconnection-tclass: Internal classes
Class, famevent-tclass: Internal classes
Class, famrequest-tclass: Internal classes

F
fam-connection: Exported classes
fam-directory-request: Internal classes
fam-event: Internal classes
fam-file-request: Internal classes
fam-request: Exported classes
famconnection-tclass: Internal classes
famevent-tclass: Internal classes
famrequest-tclass: Internal classes

P
Package, cl-fam: The cl-fam package

S
System, cl-fam: The cl-fam system

Jump to:   C   F   P   S