async_inotify v0.16.0 · OCaml Package

Async-friendly bindings to inotify, see man 7 inotify.

Be aware that the interface of inotify makes it easy to write code with race conditions or other subtle pitfalls. For instance, stat'ing a file then watching it means you have lost any events between the stat and the watch. Or the behavior when watching a path whose inode has multiple hardlinks is non-obvious.

type t

type file_info = string * Async.Unix.Stats.t

module Event : sig ... end

type modify_event_selector = [

| `Any_change
(*
Send a Modified event whenever the contents of the file changes (which can be very often when writing a large file)
*)
| `Closed_writable_fd
(*
Only send a Modify event when someone with a file descriptor with write permission to that file is closed. There are usually many fewer of these events (for large files), but they come later.
*)

]

val create : 
  ?modify_event_selector:modify_event_selector ->
  ?recursive:bool ->
  ?watch_new_dirs:bool ->
  ?events:Event.Selector.t list ->
  ?wait_to_consolidate_moves:Core.Time_float.Span.t ->
  string ->
  (t * file_info list * Event.t Async.Pipe.Reader.t) Async.Deferred.t

create path creates an inotify watching path. Returns

the inotify type t itself
the list of files currently being watched. By default, recursively watches all subdirectories of the given path. See add_all for caveats.
a pipe of all events coming from t

When watch_new_dirs, directories added after create will be watched.

~events specifies how to watch path and its descendants. When watch_new_dirs, this will always watch for Created and Moved events, even if not included in events. Note that the automatic inclusion of Created and Moved events if watch_new_dirs is only a property of create; subsequent calls to add t/add_all t will not automatically include these, even if t was created with watch_new_dirs.

wait_to_consolidate_moves specifies whether to wait a little bit after seeing a Move (Away _) event for the corresponding Move (Into, _) event, so you are more likely to get a single Move (Move _).

val create_empty : 
  modify_event_selector:modify_event_selector ->
  (t * Event.t Async.Pipe.Reader.t) Async.Deferred.t

create_empty modify_event_selector creates an inotify that watches nothing until add or add_all is called.

It returns the pipe of all events coming from t.

val stop : t -> unit Async.Deferred.t

stop t stops watching for notifications. The pipe of events is closed once all remaining have been read. Any use of add/remove from this point will raise.

val stopped : t -> bool

val add : ?events:Event.Selector.t list -> t -> string -> unit Async.Deferred.t

add t path add the path to t to be watched

val add_all : 
  ?skip_dir:((string * Async.Unix.Stats.t) -> bool Async.Deferred.t) ->
  ?events:Event.Selector.t list ->
  t ->
  string ->
  file_info list Async.Deferred.t

add_all t path watches path and all its current subdirectories recursively. This may generate events in the event pipe that are older than the returned file info, in the presence of concurrent modification to the filesystem.

val remove : t -> string -> unit Async.Deferred.t

remove t path remove the path from t

package async_inotify