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. |
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.
enum mrpc_conn_counter |
Statistics counters maintained by a connection.
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. |
int mrpc_conn_create | ( | struct mrpc_connection ** | new_conn, | |
struct mrpc_conn_set * | set, | |||
void * | data | |||
) |
Create a new connection handle.
[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 |
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:
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.
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.
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.
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 |
ENOENT:
could not look up the specified hostECONNREFUSED:
connection refusedETIMEDOUT:
connection timed outEMFILE:
too many open filesMake 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.
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 |
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.
conn | The connection handle | |
fd | The file descriptor to bind |
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.
conn | The connection handle | |
counter | The particular counter being requested | |
[out] | result | The current value of the counter |
int mrpc_conn_close | ( | struct mrpc_connection * | conn | ) |
Close an existing connection.
conn | The connection to close |
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.
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.