Module Uq_engines


module Uq_engines: sig .. end
An engine performs a certain task in an autonomous way. Engines are attached to a Unixqueue.event_system, and do their task by generating events for resources of the operating system, and by handling such events. Engines are in one of four states: They may be still working, they may be done, they may be aborted, or they may be in an error state. The three latter states a called final states, because they indicate that the engine has stopped operation.

It is possible to ask an engine to notify another object when it changes its state. For simplicity, notification is done by invoking a callback function, and not by issuing notification events.



THREAD SAFETY

Unclear.

Exceptions


exception Closed_channel
Raised when a method of a closed channel object is called (only channel methods count).

This exception should be regarded as equivalent to Netchannels.Closed_channel, but it is not the same exception.

exception Broken_communication
Engines indicate this error when they cannot continue because the other endpoint of communication signals an error.

This exception is not raised, but used as argument of the `Error state.

exception Watchdog_timeout
Used by the watchdog engine to indicate a timeout.

This exception is not raised, but used as argument of the `Error state.

exception Addressing_method_not_supported
Raised by client_socket_connector and server_socket_acceptor to indicate that the passed address is not supported by the class.

Engine definition


type 'a engine_state = [ `Aborted | `Done of 'a | `Error of exn | `Working of int ] 
The type of states with result values of type 't:
class type ['a] engine = object .. end
This class type defines the interface an engine must support.

Generic functions and classes


val when_state : ?is_done:('a -> unit) ->
?is_error:(exn -> unit) ->
?is_aborted:(unit -> unit) -> 'a #engine -> unit
Watches the state of the argument engine, and arranges that one of the functions is called when a final state is reached. After the function has been called, the engine is no longer watched.



is_done : The state transitions to `Done. The argument of is_done is the argument of the `Done state.
is_error : The state transitions to `Error. The argument of is_error is the argument of the `Error state.
is_aborted : The state transitions to `Aborted.
class [['a, 'b]] map_engine : map_done:'a -> 'b engine_state -> ?map_error:exn -> 'b engine_state -> ?map_aborted:unit -> 'b engine_state -> 'a #engine -> ['b] engine
The map_engine observes the argument engine, and when the state changes to `Done, `Error, or `Aborted, the corresponding mapping function is called, and the resulting state becomes the state of the mapped engine.
class ['a] const_engine : 'a engine_state -> Unixqueue.event_system -> ['a] engine
This engine transitions from its initial state `Working 0 in one step to the passed constant state.
class [['a, 'b]] seq_engine : 'a #engine -> 'a -> 'b #engine -> ['b] engine
This engine runs two engines in sequential order.
class [['a, 'b]] sync_engine : 'a #engine -> 'b #engine -> [('a * 'b)] engine
This engine runs two engines in parallel, and waits until both are `Done (synchronization).

Fundamental engines


class poll_engine : ?extra_match:exn -> bool -> (Unixqueue.operation * float) list -> Unixqueue.event_system -> object .. end
This engine waits until one of the passed operations can be carried out, or until one of the operations times out.
class poll_process_engine : ?period:float -> pid:int -> Unixqueue.event_system -> [Unix.process_status] engine
This engine waits until the process with the ID pid terminates.
class watchdog : float -> 'a #engine -> [unit] engine
A watchdog engine checks whether the argument engine makes progress, and if there is no progress for the passed number of seconds, the engine is aborted, and the watchdog state changes to `Error Watchdog_timeout.

Transfer engines



Transfer engines copy data between file descriptors.
class type async_out_channel = object .. end
An asynchrounous output channel provides methods to output data to a stream descriptor.
class type async_in_channel = object .. end
An asynchrounous input channel provides methods to input data from a stream descriptor.
class receiver : src:Unix.file_descr -> dst:#async_out_channel -> ?close_src:bool -> ?close_dst:bool -> Unixqueue.event_system -> [unit] engine
This engine copies all data from the src file descriptor to the dst output channel.
class sender : src:#async_in_channel -> dst:Unix.file_descr -> ?close_src:bool -> ?close_dst:bool -> Unixqueue.event_system -> [unit] engine
This engine copies all data from the src input channel to the dst file descriptor.
class output_async_descr : dst:Unix.file_descr -> ?buffer_size:int -> ?close_dst:bool -> Unixqueue.event_system -> object .. end
This engine implements an async_out_channel for the output descriptor dst.

Note that the class for the corresponding input case, input_async_descr, is not yet written. Such a class does not provide new functionality, as one can always read with receiver from file descriptors, and this is even the preferable way.
type copy_task = [ `Bidirectional of Unix.file_descr * Unix.file_descr
| `Tridirectional of Unix.file_descr * Unix.file_descr * Unix.file_descr
| `Uni_socket of Unix.file_descr * Unix.file_descr
| `Unidirectional of Unix.file_descr * Unix.file_descr ]
Specifies the task the copier class has to do:


class copier : copy_task -> Unixqueue.event_system -> [unit] engine
This engine copies data between file descriptors as specified by the copy_task argument.

Socket engines


type sockspec = [ `Sock_inet of Unix.socket_type * Unix.inet_addr * int
| `Sock_inet_byname of Unix.socket_type * string * int
| `Sock_unix of Unix.socket_type * string ]
Extended names for socket addresses. Currently, these naming schemes are supported: It is currently not possible to name IP sockets that are bound to several IP addresses but not all IP addresses of the host.
type connect_address = [ `Command of string * (int -> Unixqueue.event_system -> unit)
| `Socket of sockspec * connect_options ]
Specifies the service to connect to:



type connect_options = {
   conn_bind : sockspec option; (*Bind the connecting socket to this address (same family as the connected socket required). None: Use an anonymous port.*)
}
val default_connect_options : connect_options
Returns the default options
type connect_status = [ `Command of Unix.file_descr * int
| `Socket of Unix.file_descr * sockspec ]
This type corresponds with Uq_engines.connect_address: An engine connecting with an address `X will return a status of `X.


val client_socket : connect_status -> Unix.file_descr
Returns the client socket contained in the connect_status
type listen_address = [ `Socket of sockspec * listen_options ] 
Specifies the resource to listen on:



type listen_options = {
   lstn_backlog : int; (*The length of the queue of not yet accepted connections.*)
   lstn_reuseaddr : bool; (*Whether to allow that the address can be immediately reused after the previous listener has its socket shut down*)
}
val default_listen_options : listen_options
Returns the default options
class type client_socket_connector = object .. end
This class type provides engines to connect to a service.
class type server_socket_acceptor = object .. end
This class type is for service providers that listen for connections.
class type server_socket_listener = object .. end
This class type represents factories for service providers
val connector : ?proxy:#client_socket_connector ->
connect_address ->
Unixqueue.event_system -> connect_status engine
This engine connects to a socket as specified by the connect_address, optionally using the proxy, and changes to the state `Done(status) when the connection is established.

If the proxy does not support the connect_address, the class will raise Addressing_method_not_supported.

The descriptor fd (part of the connect_status) is in non-blocking mode, and the close-on-exec flag is set. It is the task of the caller to close this descriptor.

The engine attaches automatically to the event system, and detaches when it is possible to do so. This depends on the type of the connection method. For direct socket connections, the engine can often detach immediately when the conection is established. For proxy connections it is required that the engine copies data to and from the file descriptor. In this case, the engine detaches when the file descriptor is closed.

It is possible that name service queries block execution.

val listener : ?proxy:#server_socket_listener ->
listen_address ->
Unixqueue.event_system -> server_socket_acceptor engine
This engine creates a server socket listening on the listen_address. If passed, the proxy is used to create the server socket.

On success, the engine goes to state `Done acc, where acc is the acceptor object (see above). The acceptor object can be used to accept incoming connections.

type datagram_type = [ `Inet_udp | `Unix_dgram ] 
- `Unix_dgram: Datagrams over Unix domain sockets
class type wrapped_datagram_socket = object .. end
A wrapped_datagram_socket allows datagrams to be sent via proxies.
class type datagram_socket_provider = object .. end
This is a factory for wrapped_datagram_socket objects.
val datagram_provider : ?proxy:#datagram_socket_provider ->
datagram_type ->
Unixqueue.event_system ->
wrapped_datagram_socket engine
This engine creates a datagram socket as demanded by the datagram_type, optionally using proxy for sending and receiving datagrams.

The socket is unconnected.

The socket is in non-blocking mode, and the close-on-exec flag is set.