The Proton Messenger API provides a mixture of synchronous and asynchronous operations to give you flexibility in deciding when you application should block waiting for I/O, and when it should not.
When sending messages, you can:
When receiving messages, you can:
pn_messenger_put(messenger)
Stage message for later transmission, and possibly transmit any messages currently staged that are not blocked. This function will not block.
pn_messenger_send(messenger)
If messenger timeout is negative (initial default), block until all staged messages have been sent.
If messenger timeout is 0, send all messages that can be sent without blocking.
If messenger timeout is positive, send all messages that can be sent until timeout expires.
note: If there are any messages that can be received when pn_messenger_send()
is called, they will be received.
pn_messenger_get(messenger, msg)
Dequeue the head of the incoming message queue to your application. This call does not block.
pn_messenger_recv(messenger)
If messenger timeout is negative(initial default), block until at least one message is received.
If timeout is 0, receive whatever messages are available, but do not block.
If timeout is positive, receive available messages until timeout expires.
note: If there are any unblocked outgoing messages, they will be sent during this call.
send a message immediately
pn_messenger_put(messenger, msg); pn_messenger_send(messenger);
enqueue a message to be sent later
pn_messenger_put(messenger, msg);
note: The message will be sent whenever it is not blocked and the Messenger code has other I/O work to be done.
block until all enqueued messages are sent
pn_messenger_set_timeout(messenger, -1); pn_messenger_send(messenger);
note: A negative timeout means ‘forever’. That is the initial default for a messenger.
send enqueued messages until a timeout occurs
pn_messenger_set_timeout(messenger, 100); /* 100 msec */ pn_messenger_send(messenger);
send all messages that can be sent without blocking
pn_messenger_set_timeout(messenger, 0); pn_messenger_send(messenger);
receive messages that can be received without blocking
pn_messenger_set_timeout(messenger, 0); pn_messenger_recv(messenger, -1);
block until at least one message is received
pn_messenger_set_timeout(messenger, -1); pn_messenger_recv(messenger, -1);
note: -1 is initial messenger default.
receive no more than a fixed number of messages
pn_messenger_recv(messenger, 10);