proton
0
|
Modules | |
Disposition | |
Data Structures | |
struct | pn_delivery_tag_t |
An AMQP delivery tag. More... | |
Typedefs | |
typedef struct pn_delivery_tag_t | pn_delivery_tag_t |
An AMQP delivery tag. More... | |
typedef struct pn_delivery_t | pn_delivery_t |
An AMQP Delivery object. More... | |
Functions | |
PN_EXTERN pn_delivery_t * | pn_delivery (pn_link_t *link, pn_delivery_tag_t tag) |
Create a delivery on a link. More... | |
PN_EXTERN void * | pn_delivery_get_context (pn_delivery_t *delivery) |
Get the application context that is associated with a delivery object. More... | |
PN_EXTERN void | pn_delivery_set_context (pn_delivery_t *delivery, void *context) |
Set a new application context for a delivery object. More... | |
PN_EXTERN pn_delivery_tag_t | pn_delivery_tag (pn_delivery_t *delivery) |
Get the tag for a delivery object. More... | |
PN_EXTERN pn_link_t * | pn_delivery_link (pn_delivery_t *delivery) |
Get the parent link for a delivery object. More... | |
PN_EXTERN pn_disposition_t * | pn_delivery_local (pn_delivery_t *delivery) |
Get the local disposition for a delivery. More... | |
PN_EXTERN uint64_t | pn_delivery_local_state (pn_delivery_t *delivery) |
Get the local disposition state for a delivery. More... | |
PN_EXTERN pn_disposition_t * | pn_delivery_remote (pn_delivery_t *delivery) |
Get the remote disposition for a delivery. More... | |
PN_EXTERN uint64_t | pn_delivery_remote_state (pn_delivery_t *delivery) |
Get the remote disposition state for a delivery. More... | |
PN_EXTERN bool | pn_delivery_settled (pn_delivery_t *delivery) |
Check if a delivery is remotely settled. More... | |
PN_EXTERN size_t | pn_delivery_pending (pn_delivery_t *delivery) |
Get the amount of pending message data for a delivery. More... | |
PN_EXTERN bool | pn_delivery_partial (pn_delivery_t *delivery) |
Check if a delivery only has partial message data. More... | |
PN_EXTERN bool | pn_delivery_writable (pn_delivery_t *delivery) |
Check if a delivery is writable. More... | |
PN_EXTERN bool | pn_delivery_readable (pn_delivery_t *delivery) |
Check if a delivery is readable. More... | |
PN_EXTERN bool | pn_delivery_updated (pn_delivery_t *delivery) |
Check if a delivery is updated. More... | |
PN_EXTERN void | pn_delivery_update (pn_delivery_t *delivery, uint64_t state) |
Update the disposition of a delivery. More... | |
PN_EXTERN void | pn_delivery_clear (pn_delivery_t *delivery) |
Clear the updated flag for a delivery. More... | |
PN_EXTERN void | pn_delivery_settle (pn_delivery_t *delivery) |
Settle a delivery. More... | |
PN_EXTERN void | pn_delivery_dump (pn_delivery_t *delivery) |
Utility function for printing details of a delivery. More... | |
PN_EXTERN bool | pn_delivery_buffered (pn_delivery_t *delivery) |
Check if a delivery is buffered. More... | |
PN_EXTERN pn_delivery_t * | pn_work_head (pn_connection_t *connection) |
Extracts the first delivery on the connection that has pending operations. More... | |
PN_EXTERN pn_delivery_t * | pn_work_next (pn_delivery_t *delivery) |
Get the next delivery on the connection that needs has pending operations. More... | |
typedef struct pn_delivery_t pn_delivery_t |
An AMQP Delivery object.
A pn_delivery_t object encapsulates all of the endpoint state associated with an AMQP Delivery. Every delivery exists within the context of a pn_link_t object.
The AMQP model for settlement is based on the lifecycle of a delivery at an endpoint. At each end of a link, a delivery is created, it exists for some period of time, and finally it is forgotten, aka settled. Note that because this lifecycle happens independently at both the sender and the receiver, there are actually four events of interest in the combined lifecycle of a given delivery:
Because the sender and receiver are operating concurrently, these events can occur in a variety of different orders, and the order of these events impacts the types of failures that may occur when transferring a delivery. Eliminating scenarios where the receiver creates the delivery first, we have the following possible sequences of interest:
In this configuration the sender settles (i.e. forgets about) the delivery before it even reaches the receiver, and if anything should happen to the delivery in-flight, there is no way to recover, hence the "at most once" semantics.
In this configuration the receiver settles the delivery first, and the sender settles once it sees the receiver has settled. Should anything happen to the delivery in-flight, the sender can resend, however the receiver may have already forgotten the delivery and so it could interpret the resend as a new delivery, hence the "at least once" semantics.
In this configuration the receiver settles only once it has seen that the sender has settled. This provides the sender the option to retransmit, and the receiver has the option to recognize (and discard) duplicates, allowing for exactly once semantics.
Note that in the last scenario the sender needs some way to know when it is safe to settle. This is where delivery state comes in. In addition to these lifecycle related events surrounding deliveries there is also the notion of a delivery state that can change over the lifetime of a delivery, e.g. it might start out as nothing, transition to PN_RECEIVED and then transition to PN_ACCEPTED. In the first two scenarios the delivery state isn't required, however in final scenario the sender would typically trigger settlement based on seeing the delivery state transition to a terminal state like PN_ACCEPTED or PN_REJECTED.
In practice settlement is controlled by application policy, so there may well be more options here, e.g. a sender might not settle strictly based on what has happened at the receiver, it might also choose to impose some time limit and settle after that period has expired, or it could simply have a sliding window of the last N deliveries and settle the oldest whenever a new one comes along.
typedef struct pn_delivery_tag_t pn_delivery_tag_t |
An AMQP delivery tag.
PN_EXTERN pn_delivery_t* pn_delivery | ( | pn_link_t * | link, |
pn_delivery_tag_t | tag | ||
) |
Create a delivery on a link.
Every delivery object within a link must be supplied with a unique tag. Links maintain a sequence of delivery object in the order that they are created.
[in] | link | a link object |
[in] | tag | the delivery tag |
PN_EXTERN bool pn_delivery_buffered | ( | pn_delivery_t * | delivery | ) |
Check if a delivery is buffered.
A delivery that is buffered has not yet been written to the wire.
Note that returning false does not imply that a delivery was definitely written to the wire. If false is returned, it is not known whether the delivery was actually written to the wire or not.
[in] | delivery | a delivery object |
PN_EXTERN void pn_delivery_clear | ( | pn_delivery_t * | delivery | ) |
Clear the updated flag for a delivery.
See pn_delivery_updated.
[in] | delivery | a delivery object |
PN_EXTERN void pn_delivery_dump | ( | pn_delivery_t * | delivery | ) |
Utility function for printing details of a delivery.
[in] | delivery | a delivery object |
PN_EXTERN void* pn_delivery_get_context | ( | pn_delivery_t * | delivery | ) |
Get the application context that is associated with a delivery object.
The application context for a delivery may be set using pn_delivery_set_context.
[in] | delivery | the delivery whose context is to be returned. |
PN_EXTERN pn_link_t* pn_delivery_link | ( | pn_delivery_t * | delivery | ) |
Get the parent link for a delivery object.
[in] | delivery | a delivery object |
PN_EXTERN pn_disposition_t* pn_delivery_local | ( | pn_delivery_t * | delivery | ) |
Get the local disposition for a delivery.
The pointer returned by this object is valid until the delivery is settled.
[in] | delivery | a delivery object |
PN_EXTERN uint64_t pn_delivery_local_state | ( | pn_delivery_t * | delivery | ) |
Get the local disposition state for a delivery.
[in] | delivery | a delivery object |
PN_EXTERN bool pn_delivery_partial | ( | pn_delivery_t * | delivery | ) |
Check if a delivery only has partial message data.
[in] | delivery | a delivery object |
PN_EXTERN size_t pn_delivery_pending | ( | pn_delivery_t * | delivery | ) |
Get the amount of pending message data for a delivery.
[in] | delivery | a delivery object |
PN_EXTERN bool pn_delivery_readable | ( | pn_delivery_t * | delivery | ) |
Check if a delivery is readable.
A delivery is considered readable if it is the current delivery on an incoming link.
[in] | delivery | a delivery object |
PN_EXTERN pn_disposition_t* pn_delivery_remote | ( | pn_delivery_t * | delivery | ) |
Get the remote disposition for a delivery.
The pointer returned by this object is valid until the delivery is settled.
[in] | delivery | a delivery object |
PN_EXTERN uint64_t pn_delivery_remote_state | ( | pn_delivery_t * | delivery | ) |
Get the remote disposition state for a delivery.
[in] | delivery | a delivery object |
PN_EXTERN void pn_delivery_set_context | ( | pn_delivery_t * | delivery, |
void * | context | ||
) |
Set a new application context for a delivery object.
The application context for a delivery object may be retrieved using pn_delivery_get_context.
[in] | delivery | the delivery object |
[in] | context | the application context |
PN_EXTERN void pn_delivery_settle | ( | pn_delivery_t * | delivery | ) |
Settle a delivery.
A settled delivery can never be used again.
[in] | delivery | a delivery object |
PN_EXTERN bool pn_delivery_settled | ( | pn_delivery_t * | delivery | ) |
Check if a delivery is remotely settled.
[in] | delivery | a delivery object |
PN_EXTERN pn_delivery_tag_t pn_delivery_tag | ( | pn_delivery_t * | delivery | ) |
Get the tag for a delivery object.
[in] | delivery | a delivery object |
PN_EXTERN void pn_delivery_update | ( | pn_delivery_t * | delivery, |
uint64_t | state | ||
) |
Update the disposition of a delivery.
When update is invoked the updated disposition of the delivery will be communicated to the peer.
[in] | delivery | a delivery object |
[in] | state | the updated delivery state |
PN_EXTERN bool pn_delivery_updated | ( | pn_delivery_t * | delivery | ) |
Check if a delivery is updated.
A delivery is considered updated whenever the peer communicates a new disposition for the delivery. Once a delivery becomes updated, it will remain so until pn_delivery_clear is called.
[in] | delivery | a delivery object |
PN_EXTERN bool pn_delivery_writable | ( | pn_delivery_t * | delivery | ) |
Check if a delivery is writable.
A delivery is considered writable if it is the current delivery on an outgoing link, and the link has positive credit.
[in] | delivery | a delivery object |
PN_EXTERN pn_delivery_t* pn_work_head | ( | pn_connection_t * | connection | ) |
Extracts the first delivery on the connection that has pending operations.
Retrieves the first delivery on the Connection that has pending operations. A readable delivery indicates message data is waiting to be read. A writable delivery indicates that message data may be sent. An updated delivery indicates that the delivery's disposition has changed. A delivery will never be both readable and writible, but it may be both readable and updated or both writiable and updated.
[in] | connection | the connection |
PN_EXTERN pn_delivery_t* pn_work_next | ( | pn_delivery_t * | delivery | ) |
Get the next delivery on the connection that needs has pending operations.
[in] | delivery | the previous delivery retrieved from either pn_work_head or pn_work_next |