16. Command Acknowledgement¶
AMPS command processing is designed to be asynchronous. The design of the server makes it possible for an application to send a command to AMPS, and receive the results of that command at a later time. Acknowledgement of commands is always optional: the server makes no requirement that an application request acknowledgement. The AMPS client libraries automatically request the acknowledgements required to maintain the guarantees the client API provides.
The status and results of a command are returned to a client in the form
of an acknowledgment, or ack
, message. AMPS can return status
updates at various checkpoints throughout the command processing
sequence.
For many applications, it may not be necessary for the application to request message acknowledgements explicitly. The AMPS clients request a set of acknowledgements by default that balance performance with error detection.
AMPS supports a variety of ack
types, and allows you to request
multiple ack types on each command. For example, the received ack type
requests that AMPS acknowledge when the command is received, while the
completed ack type requests that AMPS acknowledge when it has completed
the command (or the portion of the command that runs immediately). Each
AMPS command supports a different set of types, and the precise meaning
of the ack
returned depends on the command that AMPS is
acknowledging.
AMPS commands are inherently asynchronous, and AMPS does not provide acknowledgement messages by default. A client must both explicitly request an acknowledgement and then receive and process that acknowledgement to know the results of a command. It is normal for time to elapse between the request and the acknowledgement, and so AMPS acknowledgements provide ways to correlate the acknowledgement with the command that produced it. This is typically done with an identifier that the client assigns to a command, which is then returned in the acknowledgement for the command.
AMPS supports the acknowledgement types listed in the following table:
Acknowledgment Type | General Description |
---|---|
completed |
The command (or a portion of the command) has completed. |
persisted |
The results of the command have been persisted to durable storage. |
processed |
AMPS has processed the command. |
received |
AMPS has received the command. |
stats |
AMPS returns statistics associated with the command. |
Table 16.1: AMPS acknowledgement messages
Not all commands support all acknowledgement types, and the meaning of each acknowledgement may differ depending on the command submitted. See the AMPS Command Reference for details.
Acknowledgements for different commands may not arrive in the order that
commands were submitted to AMPS. For example, a publish
command to a
topic that uses synchronous replication will not return a persisted
acknowledgment until the synchronous replication destinations have
persisted the message. If the client issues a subscribe
command in
the meantime, the processed
acknowledgement for the subscribe
command – indicating that AMPS has processed the subscription request
– may well return before the persisted
acknowledgement.
Requesting Acknowledgements¶
Acknowledgements from the AMPS server are always optional. The AMPS clients will request acknowledgements as necessary for processing and error reporting. In addition, an application can request acknowledgements as necessary to meet the requirements of an application.
The AMPS Command Guide contains information on the acknowledgement types available for each command and the meaning of those acknowledgements.
Receiving Acknowledgements¶
Acknowledgements for a specific command or subscription are delivered as a part of the message stream for that command. In an AMPS client, this means that whatever method an application is using to receive responses from AMPS will include acknowledgement messages.
Acknowledgements from AMPS have a command type of ack
. This command type
is reserved for responses from AMPS to a client. The CommandId
of the
acknowledgement message contains the CommandId
provided by the client
on the command that AMPS is responding to. The client uses this CommandId
to route the acknowledgement message to the correct message processor in
the application.
Notice that when acknowledgements are _conflated_ – that is, the acknowledgement refers to a number of publish commands – AMPS does not include a command ID in the acknowledgement message. Further details are provided at Acknowledgement Conflation and Publish Acknowledgements.
Bookmark Subscriptions and Completed Acknowledgements¶
When AMPS is processing a bookmark subscription, a completed
acknowledgement indicates that the subscription has completed replay from the
transaction log. Messages delivered on the subscription after the
completed
acknowledgement are from new publishes.
Acknowledgement Conflation and Publish Acknowledgements¶
For some commands, AMPS will conflate acknowledgements and return acknowledgements for multiple commands at one time. When AMPS conflates acknowledgements, AMPS provides an identifier other than the command identifier that describes which commands the acknowledgement applies to.
For example, when a transaction log is configured, AMPS conflates
persisted
acknowledgements in response to publish
commands
and sow_delete
commands. These conflated
acknowledgements contain the last client sequence number that the
acknowledgement applies to rather than the command identifiers or
sequence numbers for all messages being acknowledged. For example, if an
application publishes messages with sequence numbers 1
, 2
,
3
, 4
, and 5
, and message 3
fails due to entitlement
restrictions, AMPS will return an ack
indicating success for message
2
, an ack
indicating failure for message 3
, and an ack
indicating success for message 5
.
AMPS produces conflated acknowledgements for a given connection approximately once a second.
To see more information about the different commands and their supported acknowledgment types, please refer to the AMPS Command Reference, provided with 4.0 and greater versions of the AMPS clients and available on the 60East web site.