Author: mgoulish
Date: Wed Mar 13 12:35:51 2013
New Revision: 1455907
URL: http://svn.apache.org/r1455907
Log:
Make docs/messenger dir, put docs in it, use
an extension for markdown files that is less
verbose, loquacious, and wordy.
Added:
qpid/proton/trunk/docs/messenger/
qpid/proton/trunk/docs/messenger/quick_start_linux.md
qpid/proton/trunk/docs/messenger/sending_and_receiving.md
Removed:
qpid/proton/trunk/docs/quick_start_linux.markdown
qpid/proton/trunk/docs/sending_and_receiving.markdown
Added: qpid/proton/trunk/docs/messenger/quick_start_linux.md
URL:
http://svn.apache.org/viewvc/qpid/proton/trunk/docs/messenger/quick_start_linux.md?rev=1455907&view=auto
==============================================================================
--- qpid/proton/trunk/docs/messenger/quick_start_linux.md (added)
+++ qpid/proton/trunk/docs/messenger/quick_start_linux.md Wed Mar 13 12:35:51
2013
@@ -0,0 +1,51 @@
+Linux Quick Start
+==============================================
+
+
+On a Linux system, these instructions take you from
+zero to running your first example code. You will
+need root privileges for one of the commands.
+
+
+
+
+Prerequisite Packages
+---------------------------------
+
+For a minimum build, you will need packages installed on your
+box for :
+
+ subversion
+ gcc
+ cmake
+ libuuid-devel
+
+
+
+Quick Start Commands
+---------------------------
+
+ mkdir ~/proton
+ cd ~/proton
+ svn co http://svn.apache.org/repos/asf/qpid/proton/trunk
+ cd ./trunk
+ mkdir ./build
+ cd ./build
+ cmake -DCMAKE_INSTALL_PREFIX=/usr ..
+ make all
+ # Become root and go to your build dir.
+ make install
+ # Stop being root.
+ # Now let's see if it works.
+ cd ~/proton/trunk/examples/messenger/c
+ cmake .
+ make
+ ./recv &
+ ./send
+ # You're done !
+ # The output you should see:
+
+ Address: amqp://0.0.0.0
+ Subject: (no subject)
+ Content: "Hello World!"
+
Added: qpid/proton/trunk/docs/messenger/sending_and_receiving.md
URL:
http://svn.apache.org/viewvc/qpid/proton/trunk/docs/messenger/sending_and_receiving.md?rev=1455907&view=auto
==============================================================================
--- qpid/proton/trunk/docs/messenger/sending_and_receiving.md (added)
+++ qpid/proton/trunk/docs/messenger/sending_and_receiving.md Wed Mar 13
12:35:51 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
