Module Procord_connection

module Procord_connection: sig .. end

type 'a t 

Connections, i.e. sockets with added features.

You may associate your own data with each connection. Parameter 'a is the type of the data that is associated with the socket.

val connect : ?timeout:float ->
       ?ping:string -> string -> int -> 'a -> 'a t

Connect to a server using a socket.

Usage: connect ?timeout ?ping hostname port data

val update : 'a t -> unit

Update a connection. Send and receive data from and to the internal buffers, send a ping message if needed, and close the connection if it is idle.

type state = 

Possible states of connections.

val state : 'a t -> state

Get the state of the connection at the last update.

val alive : 'a t -> bool

Return whether a connection is alive.

Return true if state is Connecting, Connected or Disconnecting. Return false if state is Disconnected.

val send : 'a t -> string -> unit

Send data to a connection.

The data is put in the connection buffer. Call update regularly to ensure the data is sent eventually.

You may call send while the connection is establishing. The data will be sent eventually if you call update.

You may call send after the socket is disconnected, but nothing will happen.

val receive : 'a t -> int -> string option

Receive data from a connection.

Usage: receive connection length

If at least length bytes are available in the connection buffer, return length bytes (not more, not less). Else, return None.

Calling receive while the connection is establishing returns None.

Note that there might still be bytes to read even if the socket is disconnected.

val receive_poll : 'a t -> int -> int -> string option

Same as receive, but do not remove the data from the buffer.

Usage: receive_poll connection offset length

If at least offset + length bytes are available in the connection buffer, return length bytes (not more, not less) starting at offset. Else, return None.

val receive_poll_part : 'a t -> int -> int -> string

Same as receive_poll, but may receive less data than requested.

Usage: receive_poll connection offset length

Return at most length bytes starting at offset in the buffer, possibly 0.

val receive_all : 'a t -> string

Same as receive, but receive everything.

Usage: receive_all connection

Receive everything which is available in the buffer, possibly nothing.

val receive_part : 'a t -> int -> string

Same as receive, but may receive less data than requested.

Usage: receive_part connection length

If at least length bytes are available from the buffer, receive length bytes. Else, receive as much bytes as possible, possibly 0.

val receive_forget : 'a t -> int -> unit

Same as receive, but do not actually return the received data.

This is more efficient if you do not need the data.

val receive_buffer_length : 'a t -> int

Return the length of the receive buffer.

val receive_buffer_empty : 'a t -> bool

Return whether the receive buffer is empty.

val close : 'a t -> unit

Close a connection if it is not closed already.

val close_nicely : ?timeout:float -> 'a t -> unit

Same as close, but wait until all data is sent first. This is the only way the state can become Disconnecting.

val data : 'a t -> 'a

Get the data associated to a connection.

val timeout : 'a t -> float option

Get the timeout argument which was passed to connect or custom.

module Sync: sig .. end

Synchronous interface to procord connections.

val remote_address : 'a t -> Unix.sockaddr

Get the remote address of a connection.

val make_address : string -> Unix.inet_addr

Make a socket address from an IPv4, IPv6 or DNS address.

type 'a set 

Client connection sets.

Sets are mutable lists of connections.

It could be argued that it would be easy to make this immutable. However, there is only one set of connection at any given time; it makes no sense to have several which live together. If a connection is closed, it should not be used anymore. Having the set mutable reflects this fact.

val empty_set : unit -> 'a set

Create a new empty set of connections.

val accept_into_set : ?timeout:float ->
       ?ping:string ->
       Unix.file_descr ->
       (Unix.sockaddr -> 'a option) -> 'a set -> unit

Accept new connections from a socket and add them to a set of connections.

Usage: accept_into_set ?timeout ?ping socket make_data connections

Function make_data is given the address of the remote peer, and shall return Some data where data is the data to associate with the connection, or None to close the connection immediately.

See Procord_connection.connect for the meaning of timeout and ping, which are applied to accepted connections.

May raise Unix_error (EBADF, ...).

val update_set : 'a set -> unit

Update all connections of a set, and remove closed connections.

val iter : 'a set -> ('a t -> unit) -> unit

Iterate on all connections of a connection set.

type waiter 

Waiters for the wait function.

val waiter : 'a t -> waiter

Make a waiter from a connection.

The waiter will wait on the socket:

• for reading, if the socket is Connected;
• for writing, if the socket is Connecting (to detect connection or errors) or if the socket is Connected and there is something to send;
• for exceptional conditions, if the socket is Connecting (although this may not be necessary) or if it is Connected.

In other words, it will wait until it is worth calling update on the connection.

val waiter_of_listening_socket : Unix.file_descr -> waiter

Make a waiter from a listening socket.

The waiter will wait on the socket for reading and for exceptional conditions.

In other words, it will wait until it is worth calling Unix.accept on the socket.

val waiter_of_set : 'a set -> waiter

Make a waiter from a set of connections.

The waiter will behave as if waiter_of_list was called on the list of waiters for all connections of a set. This list may change as the set grows and shrinks.

In other words, it will wait until it is worth calling update_set on the set of connections.

val waiter_custom : ?read:Unix.file_descr list ->
       ?write:Unix.file_descr list ->
       ?except:Unix.file_descr list -> unit -> waiter

Make a custom waiter from file descriptors.

The waiter will wait:

• for reading on all file descriptors in read;
• for writing on all file descriptors in write;
• for exceptional conditions on all file descriptors in except.

val waiter_of_list : waiter list -> waiter

Make a waiter from a list of waiters.

The waiter will wait until one of the waiters in the list wants to stop waiting.

val instanciate_waiter : waiter ->
       Unix.file_descr list * Unix.file_descr list * Unix.file_descr list

Get the file descriptor lists for Unix.select from a waiter.

Allows you to call Unix.select yourself.

val wait : ?timeout:float -> waiter -> bool

Wait until something new happens.

val wait' : ?timeout:float -> waiter -> unit

Same as wait but ignore the result.

val custom : ?timeout:float ->
       ?ping:string ->
       ?input:Unix.file_descr ->
       ?output:Unix.file_descr ->
       ?remote_address:Unix.sockaddr -> 'a -> 'a t

Create a connection from custom file descriptors.

Similar to connect, but instead of taking an address as input, take file descriptors.