| Sending and Receiving Messages |
| ======================================================= |
| |
| 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: |
| |
| * send a message immediately, |
| * enqueue a message to be sent later, |
| * block until all enqueued messages are sent, |
| * send enqueued messages until a timeout occurs, or |
| * send all messages that can be sent without blocking. |
| |
| When receiving messages, you can: |
| |
| * receive messages that can be received without blocking, |
| * block until at least one message is received, |
| * receive no more than a fixed number of messages. |
| |
| |
| |
| Functions |
| ------------------------------ |
| |
| * `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.* |
| |
| |
| |
| |
| |
| Examples |
| ------------------------------ |
| |
| * 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); |
| |