Connection management

Connection management routines. More...

Functions
dpl_status_t	dpl_try_connect (dpl_ctx_t *ctx, dpl_req_t *req, dpl_conn_t **connp)
	Get a connection from the context. More...
void	dpl_conn_release (dpl_conn_t *conn)
	Release the connection after use. More...
void	dpl_conn_terminate (dpl_conn_t *conn)
	Release and immediately terminate a connection. More...
dpl_status_t	dpl_conn_writev_all (dpl_conn_t *conn, struct iovec *iov, int n_iov, int timeout)
	Write an IO vector to the connection. More...
dpl_conn_t *	dpl_conn_open_file (dpl_ctx_t *ctx, int fd)
	Create a connection to a local file. More...

Detailed Description

Function Documentation

dpl_conn_t* dpl_conn_open_file	(	dpl_ctx_t *	ctx,
		int	fd
	)

This function is used by the posix backend to create a connection which reads from or writes to an open local file. Call dpl_conn_release() to release the connection when you have finished using it.

Parameters

ctx	the context from which to create a connection
fd	an open file descriptor for a local file

Returns

a new context, or NULL on failure

void dpl_conn_release

(

dpl_conn_t *

conn

)

Releases a connection when you have finished using it. The connection cannot be used after calling dpl_conn_release(). Note that dpl_conn_release() may choose to keep the connection in an idle state for later re-use, i.e. the same connection may be returned from a future call to dpl_try_connect(). This means you should not call dpl_conn_release() if there has been an error condition on the connection; instead you should call dpl_conn_terminate().

Parameters

conn	connection to release

void dpl_conn_terminate

(

dpl_conn_t *

conn

)

Releases a connection when you have finished using it, with immediate destruction of the underlying network socket. Call this instead of dpl_conn_release() if you have encountered any error conditions on the connection.

Parameters

conn	connection to release

dpl_status_t dpl_conn_writev_all	(	dpl_conn_t *	conn,
		struct iovec *	iov,
		int	n_iov,
		int	timeout
	)

Writes an IO vector to the connection. If the use_https variable in the profile is true, the data will be written via SSL. All the data is written, without partial writes. The iov structure may be modified. Note that timeout is not implemented for SSL, due to a limitation of the SSL library.

Parameters

conn	the connection to write to
iov	IO vector which points to data to write
length	of the IO vector
timeout	per-write timeout in seconds or -1 for no timeout

Return values

DPL_SUCCESS

on success, or

Returns

a Droplet error code on failure

dpl_status_t dpl_try_connect	(	dpl_ctx_t *	ctx,
		dpl_req_t *	req,
		dpl_conn_t **	connp
	)

Creates or re-uses a connection suitable for use with the request req. The calling thread is guaranteed exclusive use of the connection. If a recently released connection is suitable, it will be returned.

If multiple hosts are specified in the host variable in the profile, connections will be distributed between those hosts in a round-robin manner. Any failure while connecting will cause the failing host to be blacklisted and the connection retried with another host; if no hosts remain, DPL_FAILURE is returned.

On success, a pointer to a connection is returned in *connp. You should release the connection by calling either dpl_conn_release() or dpl_conn_terminate(). On error the value in *connp is unchanged.

Parameters

	ctx	the context from which to create a connection
	req	the request for which this connection will be used
[out]	connp	used to return the new connection

Return values

DPL_SUCCESS

on success, or

Returns

a Droplet error code on failure