libu8
u8srvfns.h File Reference

These functions provide a scaffolding for internet servers of various sorts, implementing a simple thread pool and listener model. More...

Data Structures

struct  U8_CLIENT_STATS
 
struct  U8_CLIENT
 struct U8_CLIENT This structure represents a particular live client of a server. More...
 
struct  U8_SERVER_THREAD
 
struct  U8_SERVER_INFO
 struct U8_SERVER_INFO describes information about a particular server socket used to listen for new connections. More...
 
struct  U8_SERVER
 struct U8_SERVER This structure represents a server's state and connections. More...
 
struct  U8_SERVER_STATS
 

Typedefs

typedef struct U8_CLIENT U8_CLIENT
 struct U8_CLIENT This structure represents a particular live client of a server. More...
 
typedef struct U8_SERVER_INFO U8_SERVER_INFO
 struct U8_SERVER_INFO describes information about a particular server socket used to listen for new connections.
 
typedef struct U8_SERVER U8_SERVER
 struct U8_SERVER This structure represents a server's state and connections.
 

Functions

U8_EXPORT struct U8_SERVERu8_init_server (struct U8_SERVER *server, u8_client(*acceptfn)(u8_server, u8_socket, struct sockaddr *, size_t), int(*servefn)(u8_client), int(*donefn)(u8_client), int(*closefn)(u8_client),...)
 Initializes a server. More...
 
U8_EXPORT int u8_server_init (struct U8_SERVER *server, int maxback, int max_queue, int n_threads, u8_client(*acceptfn)(u8_server, u8_socket, struct sockaddr *, size_t), int(*servefn)(u8_client), int(*closefn)(u8_client))
 Initializes a server. More...
 
U8_EXPORT int u8_add_server (struct U8_SERVER *server, u8_string hostname, int port)
 Configures a server to listen on a particular address (port/host or file) More...
 
U8_EXPORT void u8_server_loop (struct U8_SERVER *server)
 Starts a loop listening for requests to a server. More...
 
U8_EXPORT int u8_push_task (struct U8_SERVER *server, u8_client client, u8_context cxt)
 Pushes a client/task onto the queue for a server. More...
 
U8_EXPORT int u8_shutdown_server (struct U8_SERVER *server, int grace)
 Shuts down a server, stopping listening and closing all connections when completed. More...
 
U8_EXPORT u8_server_stats u8_server_statistics (u8_server server, struct U8_SERVER_STATS *stats)
 Returns activity statistics for a server. More...
 
U8_EXPORT u8_server_stats u8_server_livestats (u8_server server, struct U8_SERVER_STATS *stats)
 Returns activity statistics for a server. More...
 
U8_EXPORT u8_server_stats u8_server_curstats (u8_server server, struct U8_SERVER_STATS *stats)
 Returns activity statistics for a server. More...
 
U8_EXPORT u8_string u8_server_status (struct U8_SERVER *server, u8_byte *buf, int buflen)
 Returns a user readable string describing the server's status, including active and pending tasks, total transactions, etc. More...
 
U8_EXPORT u8_string u8_server_status_raw (struct U8_SERVER *server, u8_byte *buf, int buflen)
 Returns a machine readable (tab-separated) string describing the server's status, including active and pending tasks, total transactions, etc. More...
 
U8_EXPORT u8_string u8_list_clients (struct U8_OUTPUT *out, struct U8_SERVER *server)
 Returns a machine readable (tab-separated) string describing each of the current clients. More...
 

Detailed Description

These functions provide a scaffolding for internet servers of various sorts, implementing a simple thread pool and listener model.

Typedef Documentation

typedef struct U8_CLIENT U8_CLIENT

struct U8_CLIENT This structure represents a particular live client of a server.

The socket field is the socket going to the client, the flags field contains flags describing the configuration and state of the client, the idstring field and statestring fields are strings identifying the client for logging and debugging, and the server field is the server (a U8_SERVER struct) to which the client is connected.

Function Documentation

U8_EXPORT int u8_add_server ( struct U8_SERVER server,
u8_string  hostname,
int  port 
)

Configures a server to listen on a particular address (port/host or file)

Parameters
servera pointer to a U8_SERVER struct
hostname(a utf-8 string) the hostname to listen for
port(an int) the port to listen on
Returns
void

References u8_clear_errors(), u8_gethostbyname(), u8_gethostname(), u8_log(), and u8_sockaddr_string().

Referenced by u8_shutdown_server().

U8_EXPORT struct U8_SERVER * u8_init_server ( struct U8_SERVER server,
u8_client(*)(u8_server, u8_socket, struct sockaddr *, size_t)  acceptfn,
int(*)(u8_client servefn,
int(*)(u8_client donefn,
int(*)(u8_client closefn,
  ... 
)

Initializes a server.

Parameters
servera pointer to a U8_SERVER struct
acceptfnthe function for accepting connections
servefnthe function called to process data for a client
donefnthe function called when data processing is done
closefnthe function called when a client is closed
Returns
a pointer to the server object This initializes a server object, allocating one if server is NULL. To actually start listening for requests, u8_add_server must be called at least once to add a listening address.
Parameters
servera pointer to a U8_SERVER struct
acceptfnthe function for accepting connections
servefnthe function called to process data for a client
donefnthe function called when data processing is done
closefnthe function called when a client is closed
...alternating property/value pairs
Returns
a pointer to the server object This initializes a server object, allocating one if server is NULL. To actually start listening for requests, u8_add_server must be called at least once to add a listening address.

References u8_log().

Referenced by u8_server_init().

U8_EXPORT u8_string u8_list_clients ( struct U8_OUTPUT out,
struct U8_SERVER server 
)

Returns a machine readable (tab-separated) string describing each of the current clients.

Parameters
outa pointer to a U8_OUTPUT struct
servera pointer to a U8_SERVER struct
Returns
the buffer string of the output stream

References u8_microtime(), and u8_printf().

U8_EXPORT int u8_push_task ( struct U8_SERVER server,
u8_client  client,
u8_context  cxt 
)

Pushes a client/task onto the queue for a server.

Parameters
servera pointer to a U8_SERVER struct
clienta pointer to a structure head-compatible with a U8_CLIENT struct
cxtthe caller context, used for debugging
Returns
1 if it did anything, zero otherwise
U8_EXPORT u8_server_stats u8_server_curstats ( u8_server  server,
struct U8_SERVER_STATS stats 
)

Returns activity statistics for a server.

Parameters
servera pointer to a U8_SERVER struct
statsa pointer to a U8_SERVER_STATS structure, or NULL
Returns
a pointer to a U8_SERVER_STATS structure (allocated if neccessary) This returns statistics over the current state of the current clients

References u8_microtime().

Referenced by u8_server_livestats().

U8_EXPORT int u8_server_init ( struct U8_SERVER server,
int  maxback,
int  max_queue,
int  n_threads,
u8_client(*)(u8_server, u8_socket, struct sockaddr *, size_t)  acceptfn,
int(*)(u8_client servefn,
int(*)(u8_client closefn 
)

Initializes a server.

Parameters
servera pointer to a U8_SERVER struct
maxbackthe maximum backlog on listening sockets
max_queuethe maximum number of tasks in the queue
n_threadsthe number of threads servicing the queue
acceptfnthe function for accepting connections
servefnthe function called to process data for a client
closefnthe function called when a client is closed
Returns
1 on success, zero otherwise This initializes a server object, allocating one if server is NULL. To actually start listening for requests, u8_add_server must be called at least once to add a listening address.

References u8_init_server(), u8_log(), and u8_microtime().

U8_EXPORT u8_server_stats u8_server_livestats ( u8_server  server,
struct U8_SERVER_STATS stats 
)

Returns activity statistics for a server.

Parameters
servera pointer to a U8_SERVER struct
statsa pointer to a U8_SERVER_STATS structure, or NULL
Returns
a pointer to a U8_SERVER_STATS structure (allocated if neccessary) This returns statistics over all of the currently open clients.

References u8_server_curstats().

Referenced by u8_server_statistics().

U8_EXPORT void u8_server_loop ( struct U8_SERVER server)

Starts a loop listening for requests to a server.

Parameters
servera pointer to a U8_SERVER struct
Returns
void

References u8_server_statistics().

U8_EXPORT u8_server_stats u8_server_statistics ( u8_server  server,
struct U8_SERVER_STATS stats 
)

Returns activity statistics for a server.

Parameters
servera pointer to a U8_SERVER struct
statsa pointer to a U8_SERVER_STATS structure, or NULL
Returns
a pointer to a U8_SERVER_STATS structure (allocated if neccessary) This returns statistics over the life of the server

References u8_server_livestats().

Referenced by u8_server_loop().

U8_EXPORT u8_string u8_server_status ( struct U8_SERVER server,
u8_byte *  buf,
int  buflen 
)

Returns a user readable string describing the server's status, including active and pending tasks, total transactions, etc.

Parameters
servera pointer to a U8_SERVER struct
bufNULL or a pointer to a buffer for the report
buflenthe size of buf if non NULL
Returns
the string of status information; if BUF was NULL, this was mallocd; otherwise, it is BUF with the output truncated to buflen

References U8_INIT_FIXED_OUTPUT, U8_INIT_STATIC_OUTPUT, and u8_printf().

U8_EXPORT u8_string u8_server_status_raw ( struct U8_SERVER server,
u8_byte *  buf,
int  buflen 
)

Returns a machine readable (tab-separated) string describing the server's status, including active and pending tasks, total transactions, etc.

Parameters
servera pointer to a U8_SERVER struct
bufNULL or a pointer to a buffer for the report
buflenthe size of buf if non NULL
Returns
the string of status information; if BUF was NULL, this was mallocd; otherwise, it is BUF with the output truncated to buflen

References U8_INIT_FIXED_OUTPUT, U8_INIT_STATIC_OUTPUT, and u8_printf().

U8_EXPORT int u8_shutdown_server ( struct U8_SERVER server,
int  grace 
)

Shuts down a server, stopping listening and closing all connections when completed.

Parameters
servera pointer to a U8_SERVER struct
gracehow long (in us) to wait for active clients to finish
Returns
1 if the server was newly and successfully closed

References u8_add_server(), u8_get_portno(), u8_graberr(), u8_log(), u8_parse_addr(), u8_reterr(), u8_seterr(), and u8_sockaddr_string().