| blob | f0278e300e03457cc84b5518ec01590decd101b2 |
1 IN: io.monitors\r
2 USING: help.markup help.syntax continuations destructors\r
3 concurrency.mailboxes quotations ;\r
4 \r
5 HELP: with-monitors\r
6 { $values { "quot" quotation } }\r
7 { $description "Calls a quotation in a new dynamic scope where file system monitor operations can be performed." }\r
8 { $errors "Throws an error if the platform does not support file system change monitors." } ;\r
9 \r
10 HELP: <monitor>\r
11 { $values { "path" "a pathname string" } { "recursive?" "a boolean" } { "monitor" "a new monitor" } }\r
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." }\r
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." } ;\r
14 \r
15 HELP: (monitor)\r
16 { $values { "path" "a pathname string" } { "recursive?" "a boolean" } { "mailbox" mailbox } { "monitor" "a new monitor" } }\r
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." }\r
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." } ;\r
19 \r
20 HELP: file-change\r
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" } "." } ;\r
22 \r
23 HELP: next-change\r
24 { $values { "monitor" "a monitor" } { "change" file-change } }\r
25 { $contract "Waits for file system changes and outputs a change descriptor for the first changed file." }\r
26 { $errors "Throws an error if the monitor is closed from another thread." } ;\r
27 \r
28 HELP: with-monitor\r
29 { $values { "path" "a pathname string" } { "recursive?" "a boolean" } { "quot" { $quotation "( monitor -- )" } } }\r
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." }\r
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." } ;\r
32 \r
33 HELP: +add-file+\r
34 { $description "Indicates that a file has been added to its parent directory." } ;\r
35 \r
36 HELP: +remove-file+\r
37 { $description "Indicates that a file has been removed from its parent directory." } ;\r
38 \r
39 HELP: +modify-file+\r
40 { $description "Indicates that a file's contents have changed." } ;\r
41 \r
42 HELP: +rename-file-old+\r
43 { $description "Indicates that a file has been renamed, and this is the old name." } ;\r
44 \r
45 HELP: +rename-file-new+\r
46 { $description "Indicates that a file has been renamed, and this is the new name." } ;\r
47 \r
48 HELP: +rename-file+\r
49 { $description "Indicates that a file has been renamed." } ;\r
50 \r
51 ARTICLE: "io.monitors.descriptors" "File system change descriptors"\r
52 "The " { $link next-change } " word outputs instances of a class:"\r
53 { $subsection file-change }\r
54 "The " { $slot "changed" } " slot holds a sequence which may contain any of the following symbols:"\r
55 { $subsection +add-file+ }\r
56 { $subsection +remove-file+ }\r
57 { $subsection +modify-file+ }\r
58 { $subsection +rename-file-old+ }\r
59 { $subsection +rename-file-new+ }\r
60 { $subsection +rename-file+ } ;\r
61 \r
62 ARTICLE: "io.monitors.platforms" "Monitors on different platforms"\r
63 "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."\r
64 $nl\r
65 "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."\r
66 { $heading "Mac OS X" }\r
67 "Factor uses " { $snippet "FSEventStream" } "s to implement monitors on Mac OS X. This requires Mac OS X 10.5 or later."\r
68 $nl\r
69 { $snippet "FSEventStream" } "s always monitor directory hierarchies recursively, and the " { $snippet "recursive?" } " parameter to " { $link <monitor> } " has no effect."\r
70 $nl\r
71 "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."\r
72 $nl\r
73 "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."\r
74 { $heading "Windows" }\r
75 "Factor uses " { $snippet "ReadDirectoryChanges" } " to implement monitors on Windows."\r
76 $nl\r
77 "Both recursive and non-recursive monitors are directly supported by the operating system."\r
78 $nl\r
79 "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."\r
80 { $heading "Linux" }\r
81 "Factor uses " { $snippet "inotify" } " to implement monitors on Linux. This requires Linux kernel version 2.6.16 or later."\r
82 $nl\r
83 "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."\r
84 $nl\r
85 "Inside a single " { $link with-monitors } " scope, only one monitor may be created for any given directory."\r
86 $nl\r
87 "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."\r
88 { $heading "BSD" }\r
89 "Factor uses " { $snippet "kqueue" } " to implement monitors on BSD."\r
90 $nl\r
91 "The " { $snippet "kqueue" } " system is limited to monitoring individual files and directories. Monitoring a directory only notifies of files being added and removed to the directory itself, not of changes to file contents."\r
92 { $heading "Windows CE" }\r
93 "Windows CE does not support monitors." ;\r
94 \r
95 ARTICLE: "io.monitors" "File system change monitors"\r
96 "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."\r
97 $nl\r
98 "Monitoring operations must be wrapped in a combinator:"\r
99 { $subsection with-monitors }\r
100 "Creating a file system change monitor and listening for changes:"\r
101 { $subsection <monitor> }\r
102 { $subsection next-change }\r
103 "An alternative programming style is where instead of having a thread listen for changes on a monitor, change notifications are posted to a mailbox:"\r
104 { $subsection (monitor) }\r
105 { $subsection "io.monitors.descriptors" }\r
106 { $subsection "io.monitors.platforms" } \r
107 "Monitors are closed by calling " { $link dispose } " or " { $link with-disposal } ". An easy way to pair construction with disposal is to use a combinator:"\r
108 { $subsection with-monitor }\r
109 "Monitors support the " { $link "io.timeouts" } "."\r
110 $nl\r
111 "An example which watches a directory for changes:"\r
112 { $code\r
113 "USE: io.monitors"\r
114 ": watch-loop ( monitor -- )"\r
115 " dup next-change . nl nl flush watch-loop ;"\r
116 ""\r
117 ": watch-directory ( path -- )"\r
118 " [ t [ watch-loop ] with-monitor ] with-monitors"\r
119 } ;\r
120 \r
121 ABOUT: "io.monitors"\r