Sending

Queueing outbound messages on a session. More...

Data Structures
struct	pbl_pp_send_job_api
	Callbacks the send queue uses to drain a job. More...
struct	pbl_pp_send_job
	Message, header included, queued without a copy. More...

Macros
#define	PBL_PP_DEFAULT_TIMEOUT_MS   4000
	Default time to wait for room in the send buffers, in milliseconds.

Functions
int	pbl_pp_send (struct pbl_pp_session *session, uint16_t endpoint_id, const uint8_t *data, size_t length, uint32_t timeout_ms)
	Send a complete message.
size_t	pbl_pp_send_buffer_max_payload (const struct pbl_pp_session *session)
	Get the largest payload a send buffer can hold.
struct pbl_pp_send_buffer *	pbl_pp_send_buffer_begin (struct pbl_pp_session *session, uint16_t endpoint_id, size_t length, uint32_t timeout_ms)
	Start building a message.
struct pbl_pp_send_buffer *	pbl_pp_send_buffer_begin_bulk (struct pbl_pp_session *session, uint16_t endpoint_id, size_t length, uint32_t timeout_ms)
	Start building a message of a bulk transfer.
bool	pbl_pp_send_buffer_write (struct pbl_pp_send_buffer *sb, const uint8_t *data, size_t length)
	Append payload to a message.
void	pbl_pp_send_buffer_end (struct pbl_pp_send_buffer *sb)
	Queue a message for sending and release the send buffer.
void	pbl_pp_send_job_submit (struct pbl_pp_session *session, struct pbl_pp_send_job **job)
	Queue a job for sending.

Detailed Description

Queueing outbound messages on a session.

pbl_pp_send() copies a complete message. A send buffer builds one piecemeal:

struct pbl_pp_send_buffer *sb =
    pbl_pp_send_buffer_begin(session, PBL_PP_ENDPOINT_PING, len, PBL_PP_DEFAULT_TIMEOUT_MS);
if (sb == NULL) {
  return -ENOMEM;
}
pbl_pp_send_buffer_write(sb, header, sizeof(*header));
pbl_pp_send_buffer_write(sb, body, body_len);
pbl_pp_send_buffer_end(sb);

Code that already owns the message memory queues it without a copy as a pbl_pp_send_job. None of these functions may be called while holding a lock the transports take.

---

Data Structure Documentation

pbl_pp_send_job

struct pbl_pp_send_job

Message, header included, queued without a copy.

Embedded in the owner's struct.

Data Fields
const struct pbl_pp_send_job_api *	api	Callbacks.
ListNode	node	Node in the session's send queue.

Macro Definition Documentation

PBL_PP_DEFAULT_TIMEOUT_MS

#define PBL_PP_DEFAULT_TIMEOUT_MS   4000

Default time to wait for room in the send buffers, in milliseconds.

Function Documentation

pbl_pp_send()

int pbl_pp_send	(	struct pbl_pp_session *	session,
		uint16_t	endpoint_id,
		const uint8_t *	data,
		size_t	length,
		uint32_t	timeout_ms
	)

Send a complete message.

Parameters

session	Destination session.
endpoint_id	Endpoint ID.
data	Payload.
length	Length of data in bytes.
timeout_ms	Maximum time to wait for room in the send buffers.

Return values

0	Queued.
-ENOTCONN	session is not open.
-EMSGSIZE	length exceeds pbl_pp_send_buffer_max_payload().
-EAGAIN	No room before timeout_ms.

pbl_pp_send_buffer_begin()

struct pbl_pp_send_buffer * pbl_pp_send_buffer_begin	(	struct pbl_pp_session *	session,
		uint16_t	endpoint_id,
		size_t	length,
		uint32_t	timeout_ms
	)

Start building a message.

Blocks until there is room for length bytes of payload, or timeout_ms expires.

Parameters

session	Destination session.
endpoint_id	Endpoint ID.
length	Payload length to reserve, in bytes.
timeout_ms	Maximum time to wait for room.

Returns

Send buffer, or NULL if session is not open, length is too large or there was no room in time.

pbl_pp_send_buffer_begin_bulk()

struct pbl_pp_send_buffer * pbl_pp_send_buffer_begin_bulk	(	struct pbl_pp_session *	session,
		uint16_t	endpoint_id,
		size_t	length,
		uint32_t	timeout_ms
	)

Start building a message of a bulk transfer.

Same as pbl_pp_send_buffer_begin(), but takes from a separate budget, so that bulk transfers do not starve interactive messages.

Parameters

session	Destination session.
endpoint_id	Endpoint ID.
length	Payload length to reserve, in bytes.
timeout_ms	Maximum time to wait for room.

Returns

Send buffer, or NULL on failure.

pbl_pp_send_buffer_end()

void pbl_pp_send_buffer_end

(

struct pbl_pp_send_buffer *

sb

)

Queue a message for sending and release the send buffer.

Parameters

sb	Send buffer.

pbl_pp_send_buffer_max_payload()

size_t pbl_pp_send_buffer_max_payload

(

const struct pbl_pp_session *

session

)

Get the largest payload a send buffer can hold.

Parameters

session

Session.

Returns

Length in bytes, 0 if session is not open.

pbl_pp_send_buffer_write()

bool pbl_pp_send_buffer_write	(	struct pbl_pp_send_buffer *	sb,
		const uint8_t *	data,
		size_t	length
	)

Append payload to a message.

Parameters

sb	Send buffer.
data	Payload data.
length	Length of data in bytes.

Returns

true if it fit in the reserved length.

pbl_pp_send_job_submit()

void pbl_pp_send_job_submit	(	struct pbl_pp_session *	session,
		struct pbl_pp_send_job **	job
	)

Queue a job for sending.

If session is not open, the job is freed and job is set to NULL.

Parameters

	session	Destination session.
[in,out]	job	Job, with pbl_pp_send_job::api set.