Connection Setup and Teardown
[Protocol-Independent API]

Detailed Description

miniRPC provides wrapper functions to handle connection setup and teardown.

Normally, clients create connections using mrpc_connect(). Servers arrange to accept connections by calling mrpc_listen() one or more times; when a connection arrives on a listening socket, the connection set's accept function will be called to notify the application of the new connection. Either end of a connection (client or server) can call mrpc_conn_close() to close an existing connection; in addition, servers can call mrpc_listen_close() to close the listening sockets previously created with mrpc_listen().

For cases in which miniRPC's connection setup code is not sufficient, miniRPC provides the mrpc_bind_fd() function. This function arranges for an existing socket to be serviced by miniRPC, and can be used if the application wishes to handle connection setup itself. This can be used, for example, to service Unix domain sockets with miniRPC.

Enumerations

enum mrpc_conn_counter {
MRPC_CONNCTR_SEND_BYTES, MRPC_CONNCTR_RECV_BYTES, MRPC_CONNCTR_SEND_MSGS, MRPC_CONNCTR_RECV_MSGS,
MRPC_CONNCTR_NR
}

Statistics counters maintained by a connection. More...

Functions

int mrpc_conn_create (struct mrpc_connection **new_conn, struct mrpc_conn_set *set, void *data)

Create a new connection handle.

void mrpc_conn_ref (struct mrpc_connection *conn)

Increment the refcount of a connection.

void mrpc_conn_unref (struct mrpc_connection *conn)

Decrement the refcount of a connection.

int mrpc_connect (struct mrpc_connection *conn, int family, const char *host, const char *service)

Make a new outgoing connection.

int mrpc_listen (struct mrpc_conn_set *set, int family, const char *listenaddr, char **service)

Start listening for incoming connections.

int mrpc_bind_fd (struct mrpc_connection *conn, int fd)

Bind an existing file descriptor to a connection handle.

int mrpc_conn_get_counter (struct mrpc_connection *conn, enum mrpc_conn_counter counter, uint64_t *result)

Get statistics counter value for the specified connection.

int mrpc_conn_close (struct mrpc_connection *conn)

Close an existing connection.

void mrpc_listen_close (struct mrpc_conn_set *set)

Close all listeners against a connection set.

Enumeration Type Documentation

enum mrpc_conn_counter

Statistics counters maintained by a connection.

Parameters:

	MRPC_CONNCTR_SEND_BYTES	The number of bytes sent on the connection
	MRPC_CONNCTR_RECV_BYTES	The number of bytes received on the connection
	MRPC_CONNCTR_SEND_MSGS	The number of miniRPC protocol messages sent on the connection
	MRPC_CONNCTR_RECV_MSGS	The number of miniRPC protocol messages received on the connection
	MRPC_CONNCTR_NR	Sentinel constant which evaluates to the number of counters supported. This does not correspond to an actual counter; passing it to mrpc_conn_get_counter() will result in EINVAL.

Function Documentation

int mrpc_conn_create	(	struct mrpc_connection **	new_conn,
		struct mrpc_conn_set *	set,
		void *	data
	)

Create a new connection handle.

Parameters:

`[out]`	new_conn	The resulting connection handle, or NULL on error
	set	The set to associate with this connection
	data	An application-specific cookie for this connection

Returns:: A POSIX error code, or 0 on success

Allocate a new connection handle with a refcount of 1, and associate it with the given connection set and application-specific pointer. This handle can then be used to make an outgoing connection with mrpc_connect(), or can be bound to an existing socket with mrpc_bind_fd(). Before the connection is completed using one of these functions, the only valid operations on the connection handle are:

Set the operations structure using the set_operations function for this protocol role
Prevent connection events from being processed with mrpc_stop_events()
Update its refcount with mrpc_conn_ref() / mrpc_conn_unref(). If the last reference is removed with mrpc_conn_unref(), the handle is freed.

If data is NULL, the application-specific pointer is set to the connection handle returned in new_conn.

While the connection handle exists, it holds a reference on the associated connection set.

void mrpc_conn_ref ( struct mrpc_connection * conn )

Increment the refcount of a connection.

Parameters:

conn

The connection

Get an additional reference to the specified connection.

void mrpc_conn_unref ( struct mrpc_connection * conn )

Decrement the refcount of a connection.

Parameters:

conn

The connection

Put a reference to the specified connection. When the refcount reaches zero and the connection is no longer active, the connection will be destroyed. Connections become active when they are connected using mrpc_connect() or mrpc_bind_fd(), or when miniRPC passes them to the connection set's accept function. Active connections become inactive after they are closed and the disconnect function returns.

int mrpc_connect	(	struct mrpc_connection *	conn,
		int	family,
		const char *	host,
		const char *	service
	)

Make a new outgoing connection.

Parameters:

	conn	The connection handle to use
	family	The address family to use, or AF_UNSPEC for any available family
	host	The hostname or address of the remote listener
	service	The service name of the remote listener

Returns:

0 on success, or a POSIX error code, including:

ENOENT: could not look up the specified host
ECONNREFUSED: connection refused
ETIMEDOUT: connection timed out
EMFILE: too many open files

Make a new outgoing connection to the specified service on the remote host and associate it with the given connection handle. The specified handle must not have been connected already. If host is NULL, miniRPC will connect to the loopback address. service can be a name or a port number represented as a string, and cannot be NULL.

This function can only be called against connections with a client protocol role.

If the protocol allows the server to issue the first RPC on the connection, the application should ensure that the correct operations structure is set on the connection handle before calling this function.

int mrpc_listen	(	struct mrpc_conn_set *	set,
		int	family,
		const char *	listenaddr,
		char **	service
	)

Start listening for incoming connections.

Parameters:

	set	The set to associate with this listener
	family	The address family to use, or AF_UNSPEC for any available family
	listenaddr	The hostname or address to listen on
`[in,out]`	service	The service identifier to listen on

Returns:: 0 if at least one listening socket is created, or the POSIX error code associated with the last error encountered

Start listening for incoming connections on the given address and service identifier, and fire the connection set's accept function whenever one arrives. If more than one address meets the specified criteria, more than one listening socket may be bound. If listenaddr is NULL, miniRPC will listen on any local interface. *service can be a name or a port number represented as a string, or NULL. If *service is NULL, family must be specified (i.e., cannot be AF_UNSPEC). In this case, miniRPC will bind to a random unused port, and will return the chosen port number in *service as a numeric string. The application should free this string with free() when no longer needed.

This function will return EINVAL if set has a client protocol role or if no accept function has been set with mrpc_set_accept_func().

int mrpc_bind_fd	(	struct mrpc_connection *	conn,
		int	fd
	)

Bind an existing file descriptor to a connection handle.

Parameters:

	conn	The connection handle
	fd	The file descriptor to bind

Returns:: A POSIX error code, or 0 on success

Associate the specified socket with an existing miniRPC connection handle. The handle must not have been connected already. The handle may have either a client or server role. The connection set's accept function will not be called. To avoid races, the application should ensure that the operations structure is set on the connection handle, if necessary, before calling this function.

The specified file descriptor must be associated with a connected socket of type SOCK_STREAM. After this call, the socket will be managed by miniRPC; the application must not read, write, or close it directly.

int mrpc_conn_get_counter	(	struct mrpc_connection *	conn,
		enum mrpc_conn_counter	counter,
		uint64_t *	result
	)

Get statistics counter value for the specified connection.

Parameters:

	conn	The connection handle
	counter	The particular counter being requested
`[out]`	result	The current value of the counter

Returns:: A POSIX error code, or 0 on success

int mrpc_conn_close ( struct mrpc_connection * conn )

Close an existing connection.

Parameters:

conn

The connection to close

Returns:: 0 on success, EALREADY if mrpc_conn_close() has already been called on this connection, or ENOTCONN if the connection handle has never been connected

Close the connection specified by conn. Protocol messages already queued for transmission will be sent before the socket is closed. Any pending synchronous RPCs will return MINIRPC_NETWORK_FAILURE, and asynchronous RPCs will have their callbacks fired with a status code of MINIRPC_NETWORK_FAILURE. Other events queued for the application will be dropped.

There is a window of time after this function returns in which further non-error events may occur on the connection. The application must be prepared to handle these events. If this function is called from an event handler for the connection being closed, and the handler has not called mrpc_release_event(), then the application is guaranteed that no more non-error events will occur on the connection once the call returns.

The application must not free any supporting data structures until the connection set's disconnect function is called for the connection, since further events may be pending. In addition, the application should not assume that the disconnect function's reason argument will be MRPC_DISC_USER, since the connection may have been terminated for another reason before mrpc_conn_close() was called.

This function may be called from an event handler, including an event handler for the connection being closed.

void mrpc_listen_close ( struct mrpc_conn_set * set )

Close all listeners against a connection set.

Parameters:

set

The connection set

Close all listening sockets associated with the connection set. The application can use this e.g. while shutting down, to prevent additional connections from being accepted while it is shutting down the existing ones.

Note that there may be unprocessed accept events in the event queue, so the application must not assume that no more accept notifications will arrive.


Enumerations
enum	mrpc_conn_counter { MRPC_CONNCTR_SEND_BYTES, MRPC_CONNCTR_RECV_BYTES, MRPC_CONNCTR_SEND_MSGS, MRPC_CONNCTR_RECV_MSGS, MRPC_CONNCTR_NR }
	Statistics counters maintained by a connection. More...
Functions
int	mrpc_conn_create (struct mrpc_connection *new_conn, struct mrpc_conn_set set, void *data)
	Create a new connection handle.
void	mrpc_conn_ref (struct mrpc_connection *conn)
	Increment the refcount of a connection.
void	mrpc_conn_unref (struct mrpc_connection *conn)
	Decrement the refcount of a connection.
int	mrpc_connect (struct mrpc_connection conn, int family, const char host, const char *service)
	Make a new outgoing connection.
int	mrpc_listen (struct mrpc_conn_set set, int family, const char listenaddr, char **service)
	Start listening for incoming connections.
int	mrpc_bind_fd (struct mrpc_connection *conn, int fd)
	Bind an existing file descriptor to a connection handle.
int	mrpc_conn_get_counter (struct mrpc_connection conn, enum mrpc_conn_counter counter, uint64_t result)
	Get statistics counter value for the specified connection.
int	mrpc_conn_close (struct mrpc_connection *conn)
	Close an existing connection.
void	mrpc_listen_close (struct mrpc_conn_set *set)
	Close all listeners against a connection set.

Connection Setup and Teardown [Protocol-Independent API]

Detailed Description

Enumerations

Functions

Enumeration Type Documentation

Function Documentation

Connection Setup and Teardown
[Protocol-Independent API]