FS Event handles allow the user to monitor a given path for changes, for example, if the file was renamed or there was a generic change in it. This handle uses the best backend for the job on each platform.
include module type of Handle with type t := t
val close : t -> Int_result.unit
Handles are closed automatically, if they are not longer referenced from the OCaml heap. Nevertheless, you should nearly always close them with
- if they wrap a file descriptor, you will sooner or later run out of file descriptors. The OCaml garbage collector doesn't give any guarantee, when orphaned memory blocks are removed.
- you might have registered some repeatedly called action (e.g. timeout, read_start,...), that prevent that all references get removed from the OCaml heap.
However, it's safe to write code in this manner:
let s = Uwt.Tcp.init () in let c = Uwt.Tcp.init () in Uwt.Tcp.nodelay s false; Uwt.Tcp.simultaneous_accepts true; if foobar () then (* no file descriptor yet assigned, no need to worry about exceptions inside foobar,... *) Lwt.return_unit (* no need to close *) else ...
If you want - for whatever reason - keep a file descriptor open for the whole lifetime of your process, remember to keep a reference to its handle.
val close_noerr : t -> unit
close_noerr return immediately (there are no useful error messages, beside perhaps a notice, that you've already closed that handle).
close_wait is only useful, if you intend to wait until all concurrent write and read threads related to this handle are canceled.
val is_active : t -> bool
Returns non-zero if the handle is active, zero if it's inactive. What "active" means depends on the type of handle:
Async.thandle is always active and cannot be deactivated, except by closing it with uv_close().
Udp.t, etc. handle - basically any handle that deals with i/o - is active when it is doing something that involves i/o, like reading, writing, connecting, accepting new connections, etc.
Rule of thumb: if a handle of type
Uwt.Foo.t has a uv_foo_start() function, then it's active from the moment that function is called. Likewise, uv_foo_stop() deactivates the handle again.
val ref' : t -> unit
Reference the given handle. References are idempotent, that is, if a handle is already referenced calling this function again will have no effect.
val unref : t -> unit
Un-reference the given handle. References are idempotent, that is, if a handle is not referenced calling this function again will have no effect.
val has_ref : t -> bool
Returns non-zero if the handle is referenced, zero otherwise.
type flags =
By default, if the fs event watcher is given a directory name, we will watch for all events in that directory. This flags overrides this behavior and makes fs_event report only changes to the directory entry itself. This flag does not affect individual files watched. This flag is currently not implemented yet on any backend.*)
Fs_eventwill try to use a kernel interface such as inotify or kqueue to detect events. This may not work on remote filesystems such as NFS mounts. This flag makes fs_event fall back to calling stat() on a regular interval. This flag is currently not implemented yet on any backend.
By default, event watcher, when watching directory, is not registering (is ignoring) changes in it's subdirectories. This flag will override this behaviour on platforms that support it.*)
Start the handle with the given callback, which will watch the specified path for changes