You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by cl...@apache.org on 2014/09/27 20:53:42 UTC
svn commit: r1627988 - /qpid/proton/trunk/proton-c/include/proton/io.h
Author: cliffjansen
Date: Sat Sep 27 18:53:42 2014
New Revision: 1627988
URL: http://svn.apache.org/r1627988
Log:
PROTON-668: Document Proton-c IO restrictions for 0.8 release
Modified:
qpid/proton/trunk/proton-c/include/proton/io.h
Modified: qpid/proton/trunk/proton-c/include/proton/io.h
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/include/proton/io.h?rev=1627988&r1=1627987&r2=1627988&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/include/proton/io.h (original)
+++ qpid/proton/trunk/proton-c/include/proton/io.h Sat Sep 27 18:53:42 2014
@@ -31,6 +31,22 @@
extern "C" {
#endif
+/**
+ * A ::pn_socket_t provides an abstract handle to an IO stream. The
+ * 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_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.
+ *
+ * pn_socket_t handles may only be used with a single pn_io_t during
+ * their lifetime.
+ */
#if defined(_WIN32) && ! defined(__CYGWIN__)
#ifdef _WIN64
typedef unsigned __int64 pn_socket_t;
@@ -43,7 +59,37 @@ typedef int pn_socket_t;
#define PN_INVALID_SOCKET (-1)
#endif
+/**
+ * A ::pn_io_t manages IO for a group of pn_socket_t handles. A
+ * pn_io_t object may have zero or one pn_selector_t selectors
+ * associated with it (see ::pn_io_selector()). If one is associated,
+ * all the pn_socket_t handles managed by a pn_io_t must use that
+ * pn_selector_t instance.
+ *
+ * The pn_io_t interface is single-threaded. All methods are intended
+ * to be used by one thread at a time, except that multiple threads
+ * may use:
+ *
+ * ::pn_write()
+ * ::pn_send()
+ * ::pn_recv()
+ * ::pn_close()
+ * ::pn_selector_select()
+ *
+ * provided at most one thread is calling ::pn_selector_select() and
+ * the other threads are operating on separate pn_socket_t handles.
+ */
typedef struct pn_io_t pn_io_t;
+
+/**
+ * A ::pn_selector_t provides a selection mechanism that allows
+ * efficient monitoring of a large number of Proton connections and
+ * listeners.
+ *
+ * External (non-Proton) sockets may also be monitored, either solely
+ * for event notification (read, write, and timer) or event
+ * notification and use with pn_io_t interfaces.
+ */
typedef struct pn_selector_t pn_selector_t;
PN_EXTERN pn_io_t *pn_io(void);
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org