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 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.

create-state

A boolean.

queue-output

A boolean.

name

A Lisp object.

handle-name

A Lisp object.

user-info

A Lisp object.

ssl-side

One of the keywords :client, :server or :both.

ssl-ctx

A symbol or a foreign pointer.

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 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 the 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. The user-info is not touched in any way by the system, and it is intended for you to pass information to the 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 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 and ipv6, 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, use the init-function argument.

See also

create-async-io-state
create-async-io-state-and-connected-tcp-socket
The Async-I/O-State API
accepting-handle
accepting-handle-local-port
close-accepting-handle