pdcomm_tcp_next_event

Function

Removes the oldest event from the endpoint's event queue.

PdcommStatus pdcomm_tcp_next_event(PdcommTcpEndpoint *endpoint, PdcommTcpEvent **out)

Declared in: #include <pdcomm_tcp.h>

Events are returned in the order they occurred. If allocating the event handle fails, the event is staged inside the endpoint and returned by the next successful call. While an event is staged, pdcomm_tcp_start(), pdcomm_tcp_stop(), pdcomm_tcp_poll(), the submit functions, and pdcomm_tcp_cancel() return #PDCOMM_BACKPRESSURE, so retrieve it before polling or submitting more work.

Parameters

Name	Description
endpoint	Live endpoint.
out	Receives the event, or NULL when the queue is empty. Set to NULL first. Must not be NULL.

Returns

#PDCOMM_OK on success, including an empty queue; #PDCOMM_INVALID_ARGUMENT when out or endpoint is NULL; #PDCOMM_ALLOCATION_FAILED when the event handle could not be allocated (the event is staged for retry); #PDCOMM_POISONED.

Notes

• Ownership: release each event with pdcomm_tcp_event_destroy(). An event owns its body and stays valid after the endpoint is destroyed.
• A configured GEM role reads events through pdcomm_gem_handle_event(); retrieving events here is still required.