uwt 0.2.1 · OCaml Package

UDP handles encapsulate UDP communication for both clients and servers.

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.

include module type of Handle_ext with type t := t

val get_send_buffer_size : t -> Int_result.int

Gets the size of the send buffer that the operating system uses for the socket.

val get_send_buffer_size_exn : t -> int

val get_recv_buffer_size : t -> Int_result.int

Gets the size of the receive buffer that the operating system uses for the socket.

val get_recv_buffer_size_exn : t -> int

val set_send_buffer_size : t -> int -> Int_result.unit

Sets the size of the send buffer that the operating system uses for the socket.

val set_send_buffer_size_exn : t -> int -> unit

val set_recv_buffer_size : t -> int -> Int_result.unit

Sets the size of the receive buffer that the operating system uses for the socket.

val set_recv_buffer_size_exn : t -> int -> unit

include module type of Handle_fileno with type t := t

val fileno : t -> Unix.file_descr uv_result

val fileno_exn : t -> Unix.file_descr

val to_handle : t -> Handle.t

val send_queue_size : t -> int

Number of bytes queued for sending; strictly shows how much information is currently queued.

val send_queue_count : t -> int

Number of send requests currently in the queue awaiting to be processed.

val init : unit -> t

See comment to Pipe.init

val init_ipv4 : unit -> t uv_result

wrappers around uv_udp_init_ex. A socket of the given type will be created immediately instead of lazy (init)

val init_ipv4_exn : unit -> t

val init_ipv6 : unit -> t uv_result

val init_ipv6_exn : unit -> t

val openudp : Unix.file_descr -> t uv_result

See comment to Pipe.openpipe

val openudp_exn : Unix.file_descr -> t

type mode =

| Ipv6_only
| Reuse_addr

val bind : ?mode:mode list -> t -> addr:sockaddr -> unit -> Int_result.unit

Bind the UDP handle to an IP address and port.

parameter mode
default mode is the empty list

val bind_exn : ?mode:mode list -> t -> addr:sockaddr -> unit -> unit

val getsockname : t -> sockaddr uv_result

Get the local IP and port of the UDP handle.

val getsockname_exn : t -> sockaddr

type membership =

| Leave_group
| Join_group

val set_membership : 
  ?interface:string ->
  t ->
  multicast:string ->
  membership ->
  Int_result.unit

Set membership for a multicast address

val set_membership_exn : 
  ?interface:string ->
  t ->
  multicast:string ->
  membership ->
  unit

val set_multicast_loop : t -> bool -> Int_result.unit

Set IP multicast loop flag. Makes multicast packets loop back to local sockets

val set_multicast_loop_exn : t -> bool -> unit

val set_multicast_ttl : t -> int -> Int_result.unit

Set the multicast ttl, ttl - 1 through 255.

val set_multicast_ttl_exn : t -> int -> unit

val set_multicast_interface : t -> string option -> Int_result.unit

Set the multicast interface to send or receive data on

val set_multicast_interface_exn : t -> string option -> unit

val set_broadcast : t -> bool -> Int_result.unit

Set broadcast on or off.

val set_broadcast_exn : t -> bool -> unit

val set_ttl : t -> int -> Int_result.unit

Set the time to live. ttl - 1 through 255.

val set_ttl_exn : t -> int -> unit

val send : ?pos:int -> ?len:int -> buf:bytes -> t -> sockaddr -> unit Lwt.t

Send data over the UDP socket. If the socket has not previously been bound with uv_udp_bind() it will be bound to 0.0.0.0 (the "all interfaces" IPv4 address) and a random port number.

val send_ba : ?pos:int -> ?len:int -> buf:buf -> t -> sockaddr -> unit Lwt.t

val send_string : 
  ?pos:int ->
  ?len:int ->
  buf:string ->
  t ->
  sockaddr ->
  unit Lwt.t

val send_raw : ?pos:int -> ?len:int -> buf:bytes -> t -> sockaddr -> unit Lwt.t

See comment to Stream.write_raw

val send_raw_ba : 
  ?pos:int ->
  ?len:int ->
  buf:buf ->
  t ->
  sockaddr ->
  unit Lwt.t

val send_raw_string : 
  ?pos:int ->
  ?len:int ->
  buf:string ->
  t ->
  sockaddr ->
  unit Lwt.t

val try_send : 
  ?pos:int ->
  ?len:int ->
  buf:bytes ->
  t ->
  sockaddr ->
  Int_result.int

Same as send, but won't queue a send request if it can't be completed immediately.

val try_send_ba : 
  ?pos:int ->
  ?len:int ->
  buf:buf ->
  t ->
  sockaddr ->
  Int_result.int

val try_send_string : 
  ?pos:int ->
  ?len:int ->
  buf:string ->
  t ->
  sockaddr ->
  Int_result.int

val try_sendv : t -> Iovec_write.t list -> sockaddr -> Int_result.int

val sendv_raw : t -> Iovec_write.t list -> sockaddr -> unit Lwt.t

val sendv : t -> Iovec_write.t list -> sockaddr -> unit Lwt.t

type recv_result =

| Data of Stdlib.Bytes.t * sockaddr option
| Partial_data of Stdlib.Bytes.t * sockaddr option
| Empty_from of sockaddr
| Transmission_error of error
(*
The type definition will likely be changed. Don't use fragile pattern matching for it
*)

val recv_start : t -> cb:(recv_result -> unit) -> Int_result.unit

Prepare for receiving data. If the socket has not previously been bound with uv_udp_bind() it is bound to 0.0.0.0 (the "all interfaces" IPv4 address) and a random port number.

val recv_start_exn : t -> cb:(recv_result -> unit) -> unit

val recv_stop : t -> Int_result.unit

Stop listening for incoming datagrams.

val recv_stop_exn : t -> unit

type recv = {

recv_len : int;
is_partial : bool;
sockaddr : sockaddr option;

}

val recv : ?pos:int -> ?len:int -> buf:bytes -> t -> recv Lwt.t

Wrappers around recv_start and recv_stop for you convenience, no callback soup. ~len should be greater than zero.

See also the comments to Stream.read. Don't pass ~len:0 or an empty buf to recv. This case is captured by uwt/libuv, not your operating system :D

val recv_ba : ?pos:int -> ?len:int -> buf:buf -> t -> recv Lwt.t

package uwt