uwt 0.2.1 · OCaml Package

Uwt main module

Basic overview:

naming conventions mirror the conventions of libuv, so you can easily consult the official libuv manual. Selected parts of the manual are now included inside the mli files (credits to Authors), the libuv manual is however more up-to-date.

Requests are translated to lwt-threads, therefore uv_req_t is kept internal.

Callbacks that are called continually are most of the time not translated to the usual lwt semantic.

Uwt is not compatible with lwt.unix. It's not a further Lwt_engine in addition to select and libev.

Uwt is not thread safe. All uwt functions should be called from your main thread.

Uwt is in beta stage. The interface is likely to change in the first official release. Feel free to open an issue and make suggestions about it :)

Please notice, that there are subtle differences compared to lwt.unix. Because all requests are accomplished by libuv (sometimes in parallel in different threads), you don't have that kind of low level control, that you have with lwt.unix. Also Lwt.cancel behaves differently and you won't notice it by looking at the type information.

Stream.write and related functions can never be canceled. The analogous write functions in Lwt_unix however are cancelable as long as the underlying file descriptor is not opened in blocking mode. (Stream.read currently returns the only cancelable thread inside Stream and its subclasses. But there is no guarantee that Tcp.read will continue to be cancelable under Windows in future libuv versions.)

Everything that is done in work threads (e.g. File I/O, DNS resolution, etc.) is cancelable, as long as the task is just queued for execution and not already running in a parallel thread. However, it's never possible to cancel a background task in Lwt_unix.

include module type of Uwt_base
  with type error = Uwt_base.error
  with type 'a uv_result = 'a Uwt_base.uv_result
  with type file = Uwt_base.file
  with type sockaddr = Uwt_base.sockaddr
  with type 'a Int_result.t = 'a Uwt_base.Int_result.t
  with type Fs_types.uv_open_flag = Uwt_base.Fs_types.uv_open_flag
  with type Fs_types.file_kind = Uwt_base.Fs_types.file_kind
  with type Fs_types.symlink_mode = Uwt_base.Fs_types.symlink_mode
  with type Fs_types.access_permission = Uwt_base.Fs_types.access_permission
  with type Fs_types.stats = Uwt_base.Fs_types.stats
  with type Misc.timeval = Uwt_base.Misc.timeval
  with type Misc.rusage = Uwt_base.Misc.rusage
  with type Misc.cpu_times = Uwt_base.Misc.cpu_times
  with type Misc.cpu_info = Uwt_base.Misc.cpu_info
  with type Misc.interface_address = Uwt_base.Misc.interface_address
  with type Misc.handle_type = Uwt_base.Misc.handle_type
  with type Misc.version = Uwt_base.Misc.version
  with type Iovec_write.t = Uwt_base.Iovec_write.t

Uwt_base contains type definitions and functions that are shared by Uwt and Uv_fs_sync

type error = Uwt_base.error =

| E2BIG
(*
argument list too long
*)
| EACCES
(*
permission denied
*)
| EADDRINUSE
(*
address already in use
*)
| EADDRNOTAVAIL
(*
address not available
*)
| EAFNOSUPPORT
(*
address family not supported
*)
| EAGAIN
(*
resource temporarily unavailable
*)
| EAI_ADDRFAMILY
(*
address family not supported
*)
| EAI_AGAIN
(*
temporary failure
*)
| EAI_BADFLAGS
(*
bad ai_flags value
*)
| EAI_BADHINTS
(*
invalid value for hints
*)
| EAI_CANCELED
(*
request canceled
*)
| EAI_FAIL
(*
permanent failure
*)
| EAI_FAMILY
(*
ai_family not supported
*)
| EAI_MEMORY
(*
out of memory
*)
| EAI_NODATA
(*
no address
*)
| EAI_NONAME
(*
unknown node or service
*)
| EAI_OVERFLOW
(*
argument buffer overflow
*)
| EAI_PROTOCOL
(*
resolved protocol is unknown
*)
| EAI_SERVICE
(*
service not available for socket type
*)
| EAI_SOCKTYPE
(*
socket type not supported
*)
| EALREADY
(*
connection already in progress
*)
| EBADF
(*
bad file descriptor
*)
| EBUSY
(*
resource busy or locked
*)
| ECANCELED
(*
operation canceled
*)
| ECHARSET
(*
Windows filenames (and similar parameters) are expected to be utf-8 encoded. ECHARSET is returned, if one parameter contains invalid byte sequences. Furthermore, ECHARSET will be returned, if your strings contain null bytes (on *nix, too).
*)
| ECONNABORTED
(*
software caused connection abort
*)
| ECONNREFUSED
(*
connection refused
*)
| ECONNRESET
(*
connection reset by peer
*)
| EDESTADDRREQ
(*
destination address required
*)
| EEXIST
(*
file already exists
*)
| EFAULT
(*
bad address in system call argument
*)
| EFBIG
(*
file too large
*)
| EHOSTUNREACH
(*
host is unreachable
*)
| EINTR
(*
interrupted system call
*)
| EINVAL
(*
invalid argument
*)
| EIO
(*
i/o error
*)
| EISCONN
(*
socket is already connected
*)
| EISDIR
(*
illegal operation on a directory
*)
| ELOOP
(*
too many symbolic links encountered
*)
| EMFILE
(*
too many open files
*)
| EMSGSIZE
(*
message too long
*)
| ENAMETOOLONG
(*
name too long
*)
| ENETDOWN
(*
network is down
*)
| ENETUNREACH
(*
network is unreachable
*)
| ENFILE
(*
file table overflow
*)
| ENOBUFS
(*
no buffer space available
*)
| ENODEV
(*
no such device
*)
| ENOENT
(*
no such file or directory
*)
| ENOMEM
(*
not enough memory
*)
| ENONET
(*
machine is not on the network
*)
| ENOPROTOOPT
(*
protocol not available
*)
| ENOSPC
(*
no space left on device
*)
| ENOSYS
(*
function not implemented
*)
| ENOTCONN
(*
socket is not connected
*)
| ENOTDIR
(*
not a directory
*)
| ENOTEMPTY
(*
directory not empty
*)
| ENOTSOCK
(*
socket operation on non-socket
*)
| ENOTSUP
(*
operation not supported on socket
*)
| EPERM
(*
operation not permitted
*)
| EPIPE
(*
broken pipe
*)
| EPROTO
(*
protocol error
*)
| EPROTONOSUPPORT
(*
protocol not supported
*)
| EPROTOTYPE
(*
protocol wrong type for socket
*)
| ERANGE
(*
result too large
*)
| EROFS
(*
read-only file system
*)
| ESHUTDOWN
(*
cannot send after transport endpoint shutdown
*)
| ESPIPE
(*
invalid seek
*)
| ESRCH
(*
no such process
*)
| ETIMEDOUT
(*
connection timed out
*)
| ETXTBSY
(*
text file is busy
*)
| EXDEV
(*
cross-device link not permitted
*)
| UNKNOWN
(*
unknown error
*)
| EOF
(*
end of file
*)
| ENXIO
(*
no such device or address
*)
| EMLINK
(*
too many links
*)
| UWT_EFATAL
(*
something happened that the author of uwt didn't expect. Probably a bug or the api of libuv has changed in the meanwhile
*)

val strerror : error -> string

error message for the given error code

val err_name : error -> string

error name for the given error code

val to_unix_error : error -> Unix.error

map error to Unix.error , Unix.EUNKNOWNERR is used, if the mapping is not possible

val of_unix_error : Unix.error -> error

get back the original Uwt.error from an exception raised by a Uwt function

type 'a uv_result = 'a Uwt_base.uv_result

type ('a, 'b) o_result = ('a, 'b) Stdlib.result =

| Ok of 'a
| Error of 'b

Please use Result.Ok or just Ok, not Uwt.Ok or Uwt_base.Ok

deprecated please use Result.result instead

type 'a result = ('a, error) o_result

deprecated please use Result.result or uv_result instead

module Int_result : sig ... end

Int_result.t is used instead of 'a result, if a function returns either an error or a non-negative integer (including unit/bool).

type file = Uwt_base.file

Abstract type for a file descriptor. Unlike Unix.file_descr it is not intended to wrap a SOCKET.

type sockaddr = Uwt_base.sockaddr

type buf =
  (char, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t

val stdin : file

File descriptor for standard input.

val stdout : file

File descriptor for standard output.

val stderr : file

File descriptor for standard error.

module Iovec_write : sig ... end

pass multiple buffers at once to a libuv write function.

module Fs_types : sig ... end

module type Fs_functions = sig ... end

module Conv : sig ... end

module Misc : sig ... end

This section contains miscellaneous functions that don't really belong in any other section.

module Sys_info : sig ... end

Information about your operating system.

module Main : sig ... end

Analogue of Lwt_main

module Fs : sig ... end

module Handle : sig ... end

Handle.t is the base type for all libuv handle types.

module Handle_ext : sig ... end

module Handle_fileno : sig ... end

The usage of fileno is unsafe and strongly discouraged. But it's sometimes necessary, if you need to interact with third parties libraries. Rules:

module Stream : sig ... end

Stream handles provide an abstraction of a duplex communication channel. Stream.t is an abstract type, libuv provides 3 stream implementations in the forn of Tcp.t, Pipe.t and Tty.t.

module Tcp : sig ... end

TCP handles are used to represent both TCP streams and servers.

module Udp : sig ... end

UDP handles encapsulate UDP communication for both clients and servers.

module Tty : sig ... end

TTY handles represent a stream for the console.

module Pipe : sig ... end

Pipe handles provide an abstraction over local domain sockets on Unix and named pipes on Windows.

module Timer : sig ... end

Timer handles are used to schedule callbacks to be called in the future.

module Signal : sig ... end

Signal handles implement Unix style signal handling on a per-event loop bases.

module Poll : sig ... end

Poll handles are used to watch file descriptors for readability, writability and disconnection similar to the purpose of poll(2).

module Fs_event : sig ... end

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.

module Fs_poll : sig ... end

FS Poll handles allow the user to monitor a given path for changes. Unlike Fs_event.t, fs poll handles use stat to detect when a file has changed so they can work on file systems where fs event handles can't.

module Process : sig ... end

Process handles will spawn a new process and allow the user to control it and establish communication channels with it using streams.

module Dns : sig ... end

libuv provides asynchronous variants of getaddrinfo and getnameinfo.

module Unix : sig ... end

Popular functions from the standard Unix module, but all calls are executed in work threads.

module C_worker : sig ... end

module Async : sig ... end

Async handles allow the user to "wakeup" the event loop and get a callback called from another (system) thread.

module Debug : sig ... end

Common helper for ad hoc debugging. Don't use them inside production code.

package uwt