package uwt

  1. Overview
  2. Docs

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.

type t
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 close, because:

  • 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
val close_wait : t -> unit Lwt.t

Prefer close or close_noerr to close_wait. close or 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:

  • A Async.t handle is always active and cannot be deactivated, except by closing it with uv_close().
  • A Pipe.t, Tcp.t, 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.

val to_handle : t -> Handle.t
type event =
  1. | Rename
  2. | Change
type flags =
  1. | Entry
    (*

    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.

    *)
  2. | Stat
    (*

    By default Fs_event will 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.

    *)
  3. | Recursive
    (*

    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.

    *)
type cb = t -> (string * event list) uv_result -> unit
val start : string -> flags list -> cb:cb -> t uv_result

Start the handle with the given callback, which will watch the specified path for changes

val start_exn : string -> flags list -> cb:cb -> t