accept-tcp-connections-creating-async-io-states

accept-tcp-connections-creating-async-io-states Function

Summary

Starts accepting TCP connections to a port within a wait-state-collection.

Package

comm

Signature

accept-tcp-connections-creating-async-io-states collection service connection-function &key init-function init-timeout backlog address nodelay keepalive ipv6 reuseport create-state name queue-output handle-name user-info ssl-ctx ssl-side ctx-configure-callback ssl-configure-callback handshake-timeout ssl-error-callback => accepting-handle

Arguments

`collection`⇩	A wait-state-collection.
`service`⇩	An integer, a string or `nil`.
`connection-function`⇩	A function designator.
`init-function`⇩	`nil` or a function designator.
`init-timeout`⇩	`nil` or a non-negative real number.
`backlog`⇩	`nil` or a positive integer.
`address`⇩	An integer, an ipv6-address object, a string or `nil`.
`nodelay`⇩	A generalized boolean.
`keepalive`⇩	A generalized boolean.
`ipv6`⇩	The keyword `:any`, `nil`, `t` or the keyword `:both`.
`reuseport`⇩	A boolean. Note: not supported on all platforms.
`create-state`⇩	A boolean.
`name`⇩	A Lisp object.
`queue-output`⇩	A boolean.
`handle-name`⇩	A Lisp object.
`user-info`⇩	A Lisp object.
`ssl-ctx`⇩	A symbol, a foreign pointer or a server ssl-abstract-context.
`ssl-side`⇩	One of the keywords `:client`, `:server` or `:both`.
`ctx-configure-callback`⇩
	A function designator or `nil`. The default value is `nil`.
`ssl-configure-callback`⇩
	A function designator or `nil`. The default value is `nil`.
`handshake-timeout`⇩	A real or `nil` (the default).
`ssl-error-callback`⇩	A function designator.

Values

accepting-handle⇩

An accepting-handle object.

Description

The function accept-tcp-connections-creating-async-io-states starts accepting TCP connections to the port service within the wait-state-collection collection.

service is interpreted as described in 25.3 Specifying the target for connecting and binding a socket.

Each time a connection is made, connection-function is called with two arguments: accepting-handle and (by default) a new async-io-state for the connected socket. The function typically calls async-io-state-read-buffer, async-io-state-write-buffer or async-io-state-read-with-checking to start performing I/O. The keyword :create-state can be used to tell accept-tcp-connections-creating-async-io-states not to create the state and instead pass the socket itself. This is useful when you want to do the I/O "somewhere else", either by creating a socket-stream and using ordinary read/write functions on it, or using a different wait-state-collection. The default value of create-state is t.

If init-function is non-nil, it is called after the listening socket has been bound to the service. init-function should take one argument: socket. socket is the socket used by the server, which can be used to determine the bound port number by calling get-socket-address.

If the port number specified by service is already in use, then accept-tcp-connections-creating-async-io-states periodically tries to bind to the port number for up to 1 minute (or init-timeout seconds if this is non-nil).

queue-output controls what happens if you try to perform a write operation on any of the states that accept-tcp-connections-creating-async-io-states creates while another write operation is in progress on the same state. When queue-output is nil, such an operation will cause an error. When queue-output is non-nil, the second write operation is queued and actually executed later. The default value of queue-output is nil.

The result accepting-handle is an object of type accepting-handle, which is the same object that will be passed to connection-function. It can be used to stop accepting and closing the socket by close-accepting-handle, and also retrieving the socket.

handle-name and user-info are stored in the accepting-handle object. user-info is not touched in any way by the system, and it is intended for you to pass information to connection-function. handle-name is used when printing the handle, but is not accessed otherwise.

When ssl-ctx is non-nil, accept-tcp-connections-creating-async-io-states always creates an async-io-state (ignoring create-state), and attaches SSL to it. ssl-side, ssl-ctx, ctx-configure-callback, ssl-configure-callback and handshake-timeout are interpreted as described in 25.8.6 Keyword arguments for use with SSL.

ssl-error-callback defaults to error. It is called when there is any error while attaching SSL to the new socket. Such errors can be either the result of an error in the configuration functions, or (more commonly) an error during the SSL handshake. ssl-error-callback is called from the thread of the wait-state-collection that was passed to accept-tcp-connections-creating-async-io-states. The socket is discarded before Sssl-error-callback is called.

For details of backlog, address, nodelay, keepalive, ipv6 and reuseport, see start-up-server.

The default value of nodelay is t.

The default value of ipv6 is :any.

The default value of name is a string "Listening".

Notes

accept-tcp-connections-creating-async-io-states binds the socket synchronously, that is when it returns successfully the socket is already bound. However, it already started accepting connections. If you need to access the socket after binding and before starting to accept connections, then do this in init-function.

When create-state is nil, the socket handle that connection-function receives can be use in a socket-stream, async-io-state or in FLI functions using the native TCP socket interface. If the socket handle is stored in a socket-stream or an async-io-state, it is closed automatically when the object is closed (by close or close-async-io-state), otherwise you need to close it by calling close-socket-handle when you have finished with it.