cp_socket

Section: cp_socket (3)
Updated: OCTOBER 2005
Index Return to Main Contents [view source]

NAME

cp_socket - tcp server socket api

SYNOPSIS

void cp_socket_init();
void cp_socket_stop_all();
void cp_socket_shutdown();
cp_socket *cp_socket_create(int port,
cp_socket_strategy strategy,
void *connection_handler);

cp_socket *cp_socket_create_ssl(int port,
                                 cp_socket_strategy strategy,
                                 void *fn,
                                 char *certificate_file,
                                 char *key_file,
                                 int verification_mode);

void cp_socket_delete(cp_socket *sock);

int cp_socket_listen(cp_socket *sock);

int cp_socket_select(cp_socket *sock);

int cp_socket_connection_close(cp_socket *sock, int fd);

SOCKET SETTINGS

void cp_socket_set_backlog(cp_socket *sock, int backlog);
void cp_socket_set_delay(cp_socket *sock, struct timeval delay);
void cp_socket_set_delay_sec(cp_socket *sock, long sec);
void cp_socket_set_delay_usec(cp_socket *sock, long usec);
void cp_socket_set_poolsize_min(cp_socket *sock, int min);
void cp_socket_set_poolsize_max(cp_socket *sock, int max);
void cp_socket_set_owner(cp_socket *sock, void *owner);

DESCRIPTION

cp_socket is a tcp server socket. cp_socket_create creates a socket to listen on the specified port. strategy may be one of CPSOCKET_STRATEGY_CALLBACK or CPSOCKET_STRATEGY_THREADPOOL. This determines the socket's behavior once a connection is accepted. If CPSOCKET_STRATEGY_CALLBACK is specified, the connection_handler function is expected to follow this prototype:


int connection_handler_callback(cp_socket *sock, int fd);

In this case the cp_socket framework accpets connections and calls the specified callback every time data is available for reading.
If CPSOCKET_STRATEGY_THREADPOOL is specified, a thread pool is instantiated to handle connections, and each connection is assigned to a separate thread. When a connection is accepted, the connection_handler specified for the socket is invoked with a newly created cp_connection_descriptor(3) parameter. It is the responsibilty of the connection handler to close the connection by calling cp_socket_connection_close and to deallocate the connection descriptor by calling cp_connection_descriptor_delete when done serving a connection. The connection handler should also check the cp_socket closing flag and exit if it is set to prevent hanging on shutdown.
The prototype for the connection handler thread function should match


void *connection_handler_fn(void *connection_descriptor);

If libcprops was configured with --enable-ssl (default), SSL features are available on sockets created with cp_socket_create_ssl, which requires the path to a certificate_file and a key_file as well. The verification_method may be one of SSL_VERIFY_NONE or SSL_VERIFY_PEER, optionally modified with SSL_VERIFY_FAIL_IF_NO_PEER_CERT and / or SSL_VERIFY_CLIENT_ONCE - see SSL_CTX_set_verify(3).

Once created, socket behavior parameters can be modified with cp_socket_set_backlog and cp_socket_set_delay. cp_socket_set_poolsize_min and cp_socket_set_poolsize_max are relevant if using CPSOCKET_STRATEGY_THREADPOOL. These settings should be made before calling cp_socket_listen.

cp_socket_listen attempts to create a SOCK_STREAM socket with socket(), bind to a local port with bind(), and set the socket to listen for connections with listen().

Finally, call cp_socket_select to begin accepting connections.

Cleanup is performed by calling cp_socket_delete.

Before using the cp_socket api, it is recommended to call cp_socket_init, which initializes global tracking structures later used to perform cleanup and installs a signal handler to trap SIGPIPE. If not invoked explicitly it will be called by cp_socket_create, but this has disadvantages in that it could result in unwanted behavior on shutdown on some systems, for instance if the first create call is made on a different thread than the thread which calls cp_socket_shutdown(), and that it will also override any previously installed handling for SIGPIPE.

cp_socket_stop_all closes all sockets and could be called by a shutdown hook to cause cp_socket_select to return.

cp_socket_shutdown should be called to perform cleanup.

Index

NAME

SYNOPSIS

SOCKET SETTINGS

DESCRIPTION

SEE ALSO

This document was created by man2html, using the manual pages.
Time: 21:26:15 GMT, January 30, 2006