Author: mgoulish
Date: Thu Mar 7 17:15:49 2013
New Revision: 1453966
URL: http://svn.apache.org/r1453966
Log:
Initial checkin.
Added:
qpid/proton/trunk/docs/
qpid/proton/trunk/docs/sending_and_receiving.markdown
Added: qpid/proton/trunk/docs/sending_and_receiving.markdown
URL:
http://svn.apache.org/viewvc/qpid/proton/trunk/docs/sending_and_receiving.markdown?rev=1453966&view=auto
==============================================================================
--- qpid/proton/trunk/docs/sending_and_receiving.markdown (added)
+++ qpid/proton/trunk/docs/sending_and_receiving.markdown Thu Mar 7 17:15:49
2013
@@ -0,0 +1,144 @@
+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 );
+
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org
For additional commands, e-mail: commits-h...@qpid.apache.org
