package async_unix

  1. Overview
  2. Docs
Legend:
Library
Module
Module type
Parameter
Class
Class type

A Server.t represents a TCP server listening on a socket.

type ('address, 'listening_on) t constraint 'address = [< Async_unix__.Unix_syscalls.Socket.Address.t ]
val sexp_of_t : ('address -> Sexplib0.Sexp.t) -> ('listening_on -> Sexplib0.Sexp.t) -> ('address, 'listening_on) t -> Sexplib0.Sexp.t
type inet = ([ `Inet of UnixLabels.inet_addr * int ], int) t
val sexp_of_inet : inet -> Sexplib0.Sexp.t
type unix = ([ `Unix of string ], string) t
val sexp_of_unix : unix -> Sexplib0.Sexp.t
val invariant : (_, _) t -> unit
val listening_on : (_, 'listening_on) t -> 'listening_on
val listening_on_address : ('address, _) t -> 'address
val close : ?close_existing_connections:bool -> (_, _) t -> unit Async_kernel.Deferred.t

close t starts closing the listening socket, and returns a deferred that becomes determined after Fd.close_finished fd on the socket's fd. It is guaranteed that t's client handler will never be called after close t. It is ok to call close multiple times on the same t; calls subsequent to the initial call will have no effect, but will return the same deferred as the original call.

With ~close_existing_connections:true, close closes the sockets of all existing connections. close does not (and cannot) stop the handlers handling the connections, but they will of course be unable to write to or read from the socket. The result of close becomes determined when all the socket file descriptors are closed and the socket's fd is closed.

val close_finished : (_, _) t -> unit Async_kernel.Deferred.t

close_finished becomes determined after Fd.close_finished fd on the socket's fd, i.e., the same deferred that close returns. close_finished differs from close in that it does not have the side effect of initiating a close.

val is_closed : (_, _) t -> bool

is_closed t returns true iff close t has been called.

val close_finished_and_handlers_determined : (_, _) t -> unit Async_kernel.Deferred.t

close_finished_and_handlers_determined t becomes determined after close_finished t is determined and the return of all active handlers is determined.

Options for server creation:

backlog is the number of clients that can have a connection pending, as with Unix.listen. Additional connections may be rejected, ignored, or enqueued anyway, depending on OS, version, and configuration.

max_connections is the maximum number of clients that can be connected simultaneously. The server will not call accept unless the number of clients is less than max_connections, although of course potential clients can have a connection pending.

max_accepts_per_batch is the maximum number of connections that the server will retrieve per blocking Unix.accept call. Servers that must handle a large number of connections tend to observe a stall in connection accept rates when under heavy load. Increasing max_accepts_per_batch will ameliorate this effect, increasing connection accept rates and overall throughput at the cost of increased contention for resources amongst connections. Servers that are under light load or ones that only service a small number of connections at a time should see little to no difference in behavior for different values of max_accepts_per_branch.

drop_incoming_connections determines whether connections will be immediately dropped when the server is created. It can be modified later with set_drop_incoming_connections; see that function for a more detailed description.

Supplying socket causes the server to use socket rather than create a new socket. In this usage, creation does not set Socket.Opt.reuseaddr to true; if you want that, you must set reuseaddr before creation.

on_handler_error determines what happens if the handler throws an exception. If an exception is raised by on_handler_error (either explicitly via `Raise, or in the closure passed to `Call) no further connections will be accepted.

val create_sock : ?max_connections:int -> ?max_accepts_per_batch:int -> ?backlog:int -> ?drop_incoming_connections:bool -> ?socket: ([ `Unconnected ], [< Async_unix__.Unix_syscalls.Socket.Address.t ] as 'address) Async_unix__.Unix_syscalls.Socket.t -> ?time_source:[> Core.read ] Async_kernel.Time_source.T1.t -> on_handler_error:[ `Call of 'address -> exn -> unit | `Ignore | `Raise ] -> ('address, 'listening_on) Where_to_listen.t -> ('address -> ([ `Active ], 'address) Async_unix__.Unix_syscalls.Socket.t -> unit Async_kernel.Deferred.t) -> ('address, 'listening_on) t Async_kernel.Deferred.t

create_sock where_to_listen handler starts a server listening to a socket as specified by where_to_listen. It returns a server once the socket is ready to accept connections. The server calls handler address socket for each client that connects. If the deferred returned by handler is ever determined, or handler raises an exception, then socket is closed.

The server will stop accepting and close the listening socket when an error handler raises (either via `Raise or `Call f where f raises), or if close is called.

val create_sock_inet : ?max_connections:int -> ?max_accepts_per_batch:int -> ?backlog:int -> ?drop_incoming_connections:bool -> ?socket: ([ `Unconnected ], [ `Inet of UnixLabels.inet_addr * int ]) Async_unix__.Unix_syscalls.Socket.t -> ?time_source:[> Core.read ] Async_kernel.Time_source.T1.t -> on_handler_error: [ `Call of [ `Inet of UnixLabels.inet_addr * int ] -> exn -> unit | `Ignore | `Raise ] -> Where_to_listen.inet -> ([ `Inet of UnixLabels.inet_addr * int ] -> ([ `Active ], [ `Inet of UnixLabels.inet_addr * int ]) Async_unix__.Unix_syscalls.Socket.t -> unit Async_kernel.Deferred.t) -> ([ `Inet of UnixLabels.inet_addr * int ], int) t

as create_sock, but only supports inet sockets, not unix sockets, and returns the server immediately rather than asynchronously.

val create : ?buffer_age_limit:Writer.buffer_age_limit -> ?max_connections:int -> ?max_accepts_per_batch:int -> ?backlog:int -> ?drop_incoming_connections:bool -> ?socket: ([ `Unconnected ], [< Async_unix__.Unix_syscalls.Socket.Address.t ] as 'address) Async_unix__.Unix_syscalls.Socket.t -> ?time_source:[> Core.read ] Async_kernel.Time_source.T1.t -> on_handler_error:[ `Call of 'address -> exn -> unit | `Ignore | `Raise ] -> ('address, 'listening_on) Where_to_listen.t -> ('address -> Reader.t -> Writer.t -> unit Async_kernel.Deferred.t) -> ('address, 'listening_on) t Async_kernel.Deferred.t

create where_to_listen handler is a convenience wrapper around create_sock that pass a reader and writer for the client socket to the callback. If the deferred returned by handler is ever determined, or handler raises an exception, then the reader and writer are closed.

buffer_age_limit passes on to the underlying writer option of the same name.

val create_inet : ?buffer_age_limit:Writer.buffer_age_limit -> ?max_connections:int -> ?max_accepts_per_batch:int -> ?backlog:int -> ?drop_incoming_connections:bool -> ?socket: ([ `Unconnected ], [ `Inet of UnixLabels.inet_addr * int ]) Async_unix__.Unix_syscalls.Socket.t -> ?time_source:[> Core.read ] Async_kernel.Time_source.T1.t -> on_handler_error: [ `Call of [ `Inet of UnixLabels.inet_addr * int ] -> exn -> unit | `Ignore | `Raise ] -> Where_to_listen.inet -> ([ `Inet of UnixLabels.inet_addr * int ] -> Reader.t -> Writer.t -> unit Async_kernel.Deferred.t) -> ([ `Inet of UnixLabels.inet_addr * int ], int) t
val listening_socket : ('address, _) t -> ([ `Passive ], 'address) Async_unix__.Unix_syscalls.Socket.t

listening_socket t accesses the listening socket, which should be used with care. An anticipated use is with Async_udp.bind_to_interface_exn. Accepting connections on the socket directly will circumvent max_connections and on_handler_error, however, and is not recommended.

val num_connections : (_, _) t -> int
val set_drop_incoming_connections : (_, _) t -> bool -> unit

set_drop_incoming_connections configures whether each incoming connection will be immediately dropped or not. This is a hack to effectively get a "pause listening" feature. We can't reliably use backlog and max_num_connections to reject incoming connections. For example, if we reach max_num_connections, we won't call accept but OS might still establish TCP connection. The client will see the connection as established but no data will be exchanged and we'd have to rely on TCP retransmit timeouts to close the connection. In many cases we would prefer to accept and then immediately close the connection. This is an intermediate solution until we do a more principled solution (but much more complicated) when we close the listening socket and then later bind and listen again when we decide to unpause the server.

drop_incoming_connections is set to false.