PROTON-1344: proactor documentation updates
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/bbeb0960 Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/bbeb0960 Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/bbeb0960 Branch: refs/heads/master Commit: bbeb096036ab67c88e8c33825aeab848605ae5c4 Parents: aadfcbb Author: Alan Conway <[email protected]> Authored: Thu Nov 17 11:17:14 2016 -0500 Committer: Alan Conway <[email protected]> Committed: Thu Nov 17 12:06:04 2016 -0500 ---------------------------------------------------------------------- proton-c/docs/api/index.md | 48 ++++++++------------- proton-c/include/proton/connection_driver.h | 17 ++++---- proton-c/include/proton/listener.h | 2 +- proton-c/include/proton/proactor.h | 55 +++++++++++++----------- proton-c/include/proton/selectable.h | 8 ++-- 5 files changed, 61 insertions(+), 69 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bbeb0960/proton-c/docs/api/index.md ---------------------------------------------------------------------- diff --git a/proton-c/docs/api/index.md b/proton-c/docs/api/index.md index 9c6009f..6a72d6b 100644 --- a/proton-c/docs/api/index.md +++ b/proton-c/docs/api/index.md @@ -1,35 +1,23 @@ Proton Documentation {#index} ==================== -## The Protocol Engine +The @ref engine is an AMQP "protocol engine". It provides functions to +manipulate AMQP endpoints and messages and generates [events](@ref event) for +the application to handle. The @ref engine has no dependencies on IO or +threading libraries. -The [Engine API](@ref engine) is a "pure AMQP" toolkit, it decodes AMQP bytes -into proton [events](@ref event) and generates AMQP bytes from application -calls. There is no IO or threading code in this part of the library. - -## Proactive event-driven programming - -The [Proactor API](@ref proactor) is a pro-active, asynchronous framework to +The @ref proactor is a proactive, asynchronous framework to build single or multi-threaded Proton C applications. It manages the IO -transport layer so you can write portable, event-driven AMQP code using the @ref -engine API. - -## IO Integration - -The [connection driver](@ref connection_driver) provides a simple bytes in/bytes -out, event-driven interface so you can read AMQP data from any source, process -the resulting [events](@ref event) and write AMQP output to any destination. It -lets you use proton in in alternate event loops, or for specialized embedded -applications. - -It is also possible to write your own implementation of the @ref proactor if you -are dealing with an unusual IO or threading framework. Any proton application -written to the proactor API will be able to use your implementation. - -## Messenger and Reactor APIs (deprecated) - -The [Messenger](@ref messenger) [Reactor](@ref reactor) APIs are older APIs -that were limited to single-threaded applications. - -Existing @ref reactor applications can be converted easily to use the @ref proactor, -since they share the same @engine API and @ref event set. +transport layer so you can write portable, event-driven AMQP code using the +@ref engine API. + +**Low-level integration**: The @ref connection_driver provides +a simple bytes in/bytes out interface to the @ref engine for a single +connection. You can use this to integrate proton with special IO libraries or +external event loops. It is also possible to write your own implementation of the +@ref proactor if you want to transparently replace proton's IO layer. + +**Old APIs**: The @ref messenger and @ref reactor APIs are +older APIs that were limited to single-threaded applications. +@ref reactor applications can be converted to use the @ref proactor since +most of the code is written to the common @ref engine API. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bbeb0960/proton-c/include/proton/connection_driver.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/connection_driver.h b/proton-c/include/proton/connection_driver.h index 4fa3fb9..8a5132b 100644 --- a/proton-c/include/proton/connection_driver.h +++ b/proton-c/include/proton/connection_driver.h @@ -26,8 +26,7 @@ * @defgroup connection_driver Connection Driver * * **Experimental**: Toolkit for integrating proton with arbitrary network or IO - * transports. Provides a single point of control for an AMQP connection and - * a simple bytes-in/bytes-out interface that lets you: + * transports via a bytes-in, bytes-out interface. * * - process AMQP-encoded bytes from some input byte stream * - generate ::pn_event_t events for your application to handle @@ -35,10 +34,10 @@ * * The pn_connection_driver_() functions provide a simplified API and extra * logic to use ::pn_connection_t and ::pn_transport_t as a unit. You can also - * access them directly for features that are not exposed via the @ref - * connection_driver API. + * access them directly for features that do not have pn_connection_driver_() + * functions * - * The engine buffers events and data, you should run it until + * The driver buffers events and data, you should run it until * pn_connection_driver_finished() is true, to ensure all reading, writing and * event handling (including ERROR and FINAL events) is finished. * @@ -62,7 +61,7 @@ * * ## Thread safety * - * The @ref engine types are not thread safe, but each connection and its + * The @ref connection_driver types are not thread safe, but each connection and its * associated types forms an independent unit. Different connections can be * processed concurrently by different threads. * @@ -89,7 +88,7 @@ typedef struct pn_connection_driver_t { } pn_connection_driver_t; /** - * Set #connection and #transport to the provided values, or create a new + * Set connection and transport to the provided values, or create a new * @ref pn_connection_t or @ref pn_transport_t if either is NULL. * The provided values belong to the connection driver and will be freed by * pn_connection_driver_destroy() @@ -114,7 +113,7 @@ PN_EXTERN int pn_connection_driver_init(pn_connection_driver_t*, pn_connection_t PN_EXTERN int pn_connection_driver_bind(pn_connection_driver_t *d); /** - * Unbind, release and free #connection and #transport. Set all pointers to + * Unbind, release and free the connection and transport. Set all pointers to * NULL. Does not free the @ref pn_connection_driver_t struct itself. */ PN_EXTERN void pn_connection_driver_destroy(pn_connection_driver_t *); @@ -191,7 +190,7 @@ PN_EXTERN pn_event_t* pn_connection_driver_next_event(pn_connection_driver_t *); PN_EXTERN bool pn_connection_driver_has_event(pn_connection_driver_t *); /** - * Return true if the the engine is closed for reading and writing and there are + * Return true if the the driver is closed for reading and writing and there are * no more events. * * Call pn_connection_driver_free() to free all related memory. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bbeb0960/proton-c/include/proton/listener.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/listener.h b/proton-c/include/proton/listener.h index 5e60649..4244e69 100644 --- a/proton-c/include/proton/listener.h +++ b/proton-c/include/proton/listener.h @@ -29,7 +29,7 @@ extern "C" { /** * @file * - * Listener API for the proton @proactor + * Listener API for the proton @ref proactor * * @defgroup listener Listener * @ingroup proactor http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bbeb0960/proton-c/include/proton/proactor.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/proactor.h b/proton-c/include/proton/proactor.h index 9d39c9c..8a2680b 100644 --- a/proton-c/include/proton/proactor.h +++ b/proton-c/include/proton/proactor.h @@ -39,9 +39,9 @@ typedef struct pn_condition_t pn_condition_t; * * **Experimental**: Proactor API for portable, multi-threaded, asynchronous applications. * - * The proactor establishes and listens for connections. It creates - * the @ref transport that sends and receives data over the network and - * delivers @ref event to application threads for handling. + * The proactor associates a @ref connection with a @ref transport, either + * by making an outgoing connection or accepting an incoming one. + * It delivers @ref event "events" to application threads for handling. * * **Multi-threading**: * The @ref proactor is thread-safe, but the @ref engine is not. The proactor @@ -53,7 +53,7 @@ typedef struct pn_condition_t pn_condition_t; */ /** - * The proactor. + * The proactor, see pn_proactor() */ typedef struct pn_proactor_t pn_proactor_t; @@ -71,9 +71,9 @@ void pn_proactor_free(pn_proactor_t*); * Connect connection to host/port. Connection and transport events will be * returned by pn_proactor_wait() * - * @param[in] connection the proactor takes ownership do not free. - * @param[in] host the address to listen on - * @param[in] port the port to connect to + * @param[in] connection the proactor takes ownership, do not free + * @param[in] host address to connect on + * @param[in] port port to connect to * * @return error on immediate error, e.g. an allocation failure. * Other errors are indicated by connection or transport events via pn_proactor_wait() @@ -84,35 +84,40 @@ int pn_proactor_connect(pn_proactor_t*, pn_connection_t *connection, const char * Start listening with listener. * pn_proactor_wait() will return a PN_LISTENER_ACCEPT event when a connection can be accepted. * - * @param[in] listener proactor takes ownership of listener, do not free. - * @param[in] host the address to listen on - * @param[in] port the port to listen on + * @param[in] listener proactor takes ownership of listener, do not free + * @param[in] host address to listen on + * @param[in] port port to listen on + * @param[in] backlog number of connection requests to queue * * @return error on immediate error, e.g. an allocation failure. * Other errors are indicated by pn_listener_condition() on the PN_LISTENER_CLOSE event. */ -int pn_proactor_listen(pn_proactor_t *p, pn_listener_t *listener, const char *host, const char *port, int backlog); +int pn_proactor_listen(pn_proactor_t *, pn_listener_t *listener, const char *host, const char *port, int backlog); /** - * Wait for events to handle. Call pn_proactor_done() after handling events. + * Wait for events to handle. * - * Thread safe: pn_proactor_wait() can be called concurrently, but the events in - * the returned ::pn_event_batch_t must be handled sequentially. + * Handle events in the returned batch by calling pn_event_batch_next() until it + * returns NULL. You must call pn_proactor_done() to when you are finished. * - * The proactor always returns events that must be handled sequentially in the - * same batch or sequentially in a later batch after pn_proactor_done(). Any - * events returned concurrently by pn_proactor_wait() are safe to handle - * concurrently. + * If you call pn_proactor_done() before finishing the batch, the remaining + * events will be returned again by another call pn_proactor_wait(). This is + * less efficient, but allows you to handle part of a batch and then hand off + * the rest to another thread. + * + * Thread safe: can be called concurrently. Events in a single batch must be + * handled in sequence, but batches returned by separate calls to + * pn_proactor_wait() can be handled concurrently. */ pn_event_batch_t *pn_proactor_wait(pn_proactor_t* d); /** * Call when done handling events. * - * It is generally most efficient to handle the entire batch in the thread - * that calls pn_proactor_wait(), then call pn_proactor_done(). If you call - * pn_proactor_done() earlier, the remaining events will be returned again by - * pn_proactor_wait(), possibly to another thread. + * Must be called exactly once to match each call to pn_proactor_wait(). + * + * Thread safe: may be called from any thread provided the exactly once rules is + * respected. */ void pn_proactor_done(pn_proactor_t* d, pn_event_batch_t *events); @@ -145,17 +150,17 @@ void pn_proactor_set_timeout(pn_proactor_t* d, pn_millis_t timeout); void pn_connection_wake(pn_connection_t *c); /** - * The proactor that created the connection. + * Return the proactor associated with a connection or null */ pn_proactor_t *pn_connection_proactor(pn_connection_t *c); /** - * Get the proactor that created the event or NULL. + * Return the proactor associated with an event or NULL. */ pn_proactor_t *pn_event_proactor(pn_event_t *); /** - * Get the listener for the event or NULL. + * Return the listener associated with an event or NULL. */ pn_listener_t *pn_event_listener(pn_event_t *); http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bbeb0960/proton-c/include/proton/selectable.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/selectable.h b/proton-c/include/proton/selectable.h index fbf3823..5eff58d 100644 --- a/proton-c/include/proton/selectable.h +++ b/proton-c/include/proton/selectable.h @@ -51,11 +51,11 @@ typedef pn_iterator_t pn_selectables_t; * pipe version is uni-directional. The network socket version is * bi-directional. Both are non-blocking. * - * pn_socket_t handles from ::pn_pipe() may only be used with - * ::pn_read(), ::pn_write(), ::pn_close() and pn_selector_select(). + * pn_socket_t handles from pn_pipe() may only be used with + * pn_read(), pn_write(), pn_close() and pn_selector_select(). * - * pn_socket_t handles from ::pn_listen(), ::pn_accept() and - * ::pn_connect() must perform further IO using Proton functions. + * pn_socket_t handles from pn_listen(), pn_accept() and + * pn_connect() must perform further IO using Proton functions. * Mixing Proton io.h functions with native IO functions on the same * handles will result in undefined behavior. * --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
