pdcomm_gem_handle_event
Function
Processes one TCP event with the GEM role and returns an owned result.
PdcommStatus pdcomm_gem_handle_event(PdcommTcpEndpoint *endpoint, PdcommTcpEvent *event, PdcommGemResult **out)Pass every event from pdcomm_tcp_next_event() in queue order. The call borrows the event exclusively while it runs; the event's TCP metadata and body remain readable afterward and the caller still owns it.
- A received primary is answered automatically when the role handles it (
reply_sentis set), reported for an application decision through the typed APIs of the other GEM headers, or reported as #PDCOMM_GEM_UNHANDLED without a reply. - A reply to a pending GEM request gives #PDCOMM_GEM_RESPONSE, #PDCOMM_GEM_INVALID_RESPONSE, or #PDCOMM_GEM_FAILED and releases the pending slot.
- A transaction failure for a pending request gives #PDCOMM_GEM_FAILED.
- Any other event gives #PDCOMM_GEM_IGNORED.
A successful call marks the event as handled by GEM; handling it again returns #PDCOMM_STALE_TOKEN. When #PDCOMM_ALLOCATION_FAILED or #PDCOMM_BACKPRESSURE is returned before that commit, the event stays unhandled and the call can be retried with the same event.
Parameters
| Name | Description |
|---|---|
endpoint | Live TCP endpoint with a GEM role. |
event | Event from pdcomm_tcp_next_event() on the same endpoint. |
out | Receives the new result. Set to NULL first, so it is NULL after every failure. Must not be NULL. |
Returns
#PDCOMM_OK when a result was produced (also for ignored, failed, invalid-response, and unhandled results); #PDCOMM_INVALID_ARGUMENT when endpoint, event, or out is NULL; #PDCOMM_STALE_TOKEN when the event was already handled, or is a received-message, transaction-failure, or W0-written event from another endpoint or an older connection generation (an old-generation failure is accepted while its request is still pending); #PDCOMM_INVALID_STATE when the endpoint has no GEM role; #PDCOMM_BACKPRESSURE when a staged TCP event exists or an automatic reply cannot be queued yet; #PDCOMM_ALLOCATION_FAILED, #PDCOMM_LIMIT_EXCEEDED, or another TCP status when the result or reply cannot be produced; #PDCOMM_POISONED when the endpoint is poisoned.
Notes
- Ownership: release the result with pdcomm_gem_result_destroy(). It owns all snapshot data and survives destruction of the event and the endpoint. Release the event separately with pdcomm_tcp_event_destroy().