basis/io/monitors/monitors-docs.factor

   1 IN: io.monitors
   2 USING: concurrency.mailboxes destructors help.markup help.syntax
   3 kernel quotations ;
   4
   5 HELP: with-monitors
   6 { $values { "quot" quotation } }
   7 { $description "Calls a quotation in a new dynamic scope where file system monitor operations can be performed." }
   8 { $errors "Throws an error if the platform does not support file system change monitors." } ;
   9
  10 HELP: <monitor>
  11 { $values { "path" "a pathname string" } { "recursive?" boolean } { "monitor" "a new monitor" } }
  12 { $contract "Opens a file system change monitor which listens for changes on " { $snippet "path" } ". The boolean indicates whether changes in subdirectories should be reported." }
  13 { $errors "Throws an error if the pathname does not exist, if a monitor could not be created or if the platform does not support monitors." } ;
  14
  15 HELP: (monitor)
  16 { $values { "path" "a pathname string" } { "recursive?" boolean } { "mailbox" mailbox } { "monitor" "a new monitor" } }
  17 { $contract "Opens a file system change monitor which listens for changes on " { $snippet "path" } " and posts notifications to " { $snippet "mailbox" } " as triples with shape " { $snippet "{ path changed monitor } " } ". The boolean indicates whether changes in subdirectories should be reported." }
  18 { $errors "Throws an error if the pathname does not exist, if a monitor could not be created or if the platform does not support monitors." } ;
  19
  20 HELP: file-change
  21 { $class-description "A change notification output by " { $link next-change } ". The " { $snippet "path" } " slot holds a pathname string. The " { $snippet "changed" } " slots holds a sequence of symbols documented in " { $link "io.monitors.descriptors" } "." } ;
  22
  23 HELP: next-change
  24 { $values { "monitor" "a monitor" } { "change" file-change } }
  25 { $contract "Waits for file system changes and outputs a change descriptor for the first changed file." }
  26 { $errors "Throws an error if the monitor is closed from another thread." } ;
  27
  28 HELP: with-monitor
  29 { $values { "path" "a pathname string" } { "recursive?" boolean } { "quot" { $quotation ( monitor -- ) } } }
  30 { $description "Opens a file system change monitor and passes it to the quotation. Closes the monitor after the quotation returns or throws an error." }
  31 { $errors "Throws an error if the pathname does not exist, if a monitor could not be created or if the platform does not support monitors." } ;
  32
  33 HELP: +add-file+
  34 { $description "Indicates that a file has been added to its parent directory." } ;
  35
  36 HELP: +remove-file+
  37 { $description "Indicates that a file has been removed from its parent directory." } ;
  38
  39 HELP: +modify-file+
  40 { $description "Indicates that a file's contents have changed." } ;
  41
  42 HELP: +rename-file-old+
  43 { $description "Indicates that a file has been renamed, and this is the old name." } ;
  44
  45 HELP: +rename-file-new+
  46 { $description "Indicates that a file has been renamed, and this is the new name." } ;
  47
  48 HELP: +rename-file+
  49 { $description "Indicates that a file has been renamed." } ;
  50
  51 ARTICLE: "io.monitors.descriptors" "File system change descriptors"
  52 "The " { $link next-change } " word outputs instances of a class:"
  53 { $subsections file-change }
  54 "The " { $slot "changed" } " slot holds a sequence which may contain any of the following symbols:"
  55 { $subsections
  56     +add-file+
  57     +remove-file+
  58     +modify-file+
  59     +rename-file-old+
  60     +rename-file-new+
  61     +rename-file+
  62 } ;
  63
  64 ARTICLE: "io.monitors.platforms" "Monitors on different platforms"
  65 "Whether the " { $slot "path" } " slot of a " { $link file-change } " contains an absolute path or a path relative to the path given to " { $link <monitor> } " is unspecified, and may even vary on the same platform. User code should not assume either case."
  66 $nl
  67 "If the immediate path being monitored was changed, then " { $snippet "path" } " will equal " { $snippet "\"\"" } "; however this condition is not reported on all platforms. See below."
  68 { $heading "Mac OS X" }
  69 "Factor uses " { $snippet "FSEventStream" } "s to implement monitors on Mac OS X. This requires Mac OS X 10.5 or later."
  70 $nl
  71 { $snippet "FSEventStream" } "s always monitor directory hierarchies recursively, and the " { $snippet "recursive?" } " parameter to " { $link <monitor> } " has no effect."
  72 $nl
  73 "The " { $snippet "changed" } " slot of the " { $link file-change } " word tuple always contains " { $link +modify-file+ } " and the " { $snippet "path" } " slot is always the directory containing the file that changed. Unlike other platforms, fine-grained information is not available."
  74 $nl
  75 "Only directories may be monitored, not individual files. Changes to the directory itself (permissions, modification time, and so on) are not reported; only changes to children are reported."
  76 { $heading "Windows" }
  77 "Factor uses " { $snippet "ReadDirectoryChanges" } " to implement monitors on Windows."
  78 $nl
  79 "Both recursive and non-recursive monitors are directly supported by the operating system."
  80 $nl
  81 "Only directories may be monitored, not individual files. Changes to the directory itself (permissions, modification time, and so on) are not reported; only changes to children are reported."
  82 { $heading "Linux" }
  83 "Factor uses " { $snippet "inotify" } " to implement monitors on Linux. This requires Linux kernel version 2.6.16 or later."
  84 $nl
  85 "Factor simulates recursive monitors by creating a hierarchy of monitors for every subdirectory, since " { $snippet "inotify" } " can only monitor a single directory. This is transparent to user code."
  86 $nl
  87 "Inside a single " { $link with-monitors } " scope, only one monitor may be created for any given directory."
  88 $nl
  89 "Both directories and files may be monitored. Unlike Mac OS X and Windows, changes to the immediate directory being monitored (permissions, modification time, and so on) are reported."
  90 ;
  91
  92 ARTICLE: "io.monitors" "File system change monitors"
  93 "File system change monitors listen for changes to file names, attributes and contents under a specified directory. They can optionally be recursive, in which case subdirectories are also monitored."
  94 $nl
  95 "Monitoring operations must be wrapped in a combinator:"
  96 { $subsections with-monitors }
  97 "Creating a file system change monitor and listening for changes:"
  98 { $subsections
  99     <monitor>
 100     next-change
 101 }
 102 "An alternative programming style is where instead of having a thread listen for changes on a monitor, change notifications are posted to a mailbox:"
 103 { $subsections
 104     (monitor)
 105     "io.monitors.descriptors"
 106     "io.monitors.platforms"
 107 }
 108 "Monitors are closed by calling " { $link dispose } " or " { $link with-disposal } ". An easy way to pair construction with disposal is to use a combinator:"
 109 { $subsections with-monitor }
 110 "Monitors support the " { $link "io.timeouts" } "."
 111 $nl
 112 "An example which watches a directory for changes:"
 113 { $code
 114     "USE: io.monitors"
 115     ""
 116     ": watch-loop ( monitor -- )"
 117     "    dup next-change path>> print flush watch-loop ;"
 118     ""
 119     ": watch-directory ( path -- )"
 120     "    [ t [ watch-loop ] with-monitor ] with-monitors ;"
 121 } ;
 122
 123 ABOUT: "io.monitors"