Qpid Proton C API  0.17.0
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Proactor

Experimental - Multithreaded IO More...

Typedefs

typedef struct pn_listener_t pn_listener_t
 A listener accepts connections.
 
typedef struct pn_proactor_t pn_proactor_t
 The proactor, see pn_proactor()
 

Functions

pn_listener_tpn_listener (void)
 Create a listener. More...
 
int pn_listener_accept (pn_listener_t *, pn_connection_t *connection)
 Asynchronously accept a connection using the listener. More...
 
pn_condition_tpn_listener_condition (pn_listener_t *l)
 Get the error condition for a listener.
 
pn_record_t * pn_listener_attachments (pn_listener_t *listener)
 Get the attachments that are associated with a listener object.
 
void pn_listener_close (pn_listener_t *l)
 Close the listener (thread safe).
 
pn_proactor_tpn_listener_proactor (pn_listener_t *c)
 The proactor associated with a listener.
 
pn_proactor_tpn_proactor (void)
 Create a proactor. More...
 
void pn_proactor_free (pn_proactor_t *proactor)
 Free the proactor. More...
 
int pn_proactor_connect (pn_proactor_t *proactor, pn_connection_t *connection, const char *host, const char *port)
 Connect connection to host/port. More...
 
int pn_proactor_listen (pn_proactor_t *proactor, pn_listener_t *listener, const char *host, const char *port, int backlog)
 Start listening with listener. More...
 
pn_event_batch_tpn_proactor_wait (pn_proactor_t *proactor)
 Wait for events to handle. More...
 
void pn_proactor_done (pn_proactor_t *proactor, pn_event_batch_t *events)
 Call when done handling a batch of events. More...
 
void pn_proactor_interrupt (pn_proactor_t *proactor)
 Cause PN_PROACTOR_INTERRUPT to be returned to exactly one call of pn_proactor_wait(). More...
 
void pn_proactor_set_timeout (pn_proactor_t *proactor, pn_millis_t timeout)
 Cause PN_PROACTOR_TIMEOUT to be returned to a thread calling wait() after timeout milliseconds. More...
 
void pn_connection_wake (pn_connection_t *connection)
 Cause a PN_CONNECTION_WAKE event to be returned by the proactor, even if there are no IO events pending for the connection. More...
 
pn_proactor_tpn_connection_proactor (pn_connection_t *connection)
 Return the proactor associated with a connection or NULL.
 
pn_proactor_tpn_event_proactor (pn_event_t *event)
 Return the proactor associated with an event or NULL.
 
pn_listener_tpn_event_listener (pn_event_t *event)
 Return the listener associated with an event or NULL.
 

Detailed Description

Experimental - Multithreaded IO

Function Documentation

void pn_connection_wake ( pn_connection_t connection)

Cause a PN_CONNECTION_WAKE event to be returned by the proactor, even if there are no IO events pending for the connection.

Note
Thread-safe: this is the only pn_connection_ function that can be called concurrently.

Wakes can be "coalesced" - if several pn_connection_wake() calls happen concurrently, there may be only one PN_CONNECTION_WAKE event.

Examples:
broker.c, and send.c.
pn_listener_t* pn_listener ( void  )

Create a listener.

You can use pn_listener_set_context() or pn_listener_attachments() to set application data that can be accessed when accepting connections.

You must pass the returned listener to pn_proactor_listen(), the proactor will free the listener when it is no longer active.

Examples:
broker.c.
int pn_listener_accept ( pn_listener_t ,
pn_connection_t connection 
)

Asynchronously accept a connection using the listener.

Parameters
[in]connectionthe listener takes ownership, do not free.
Examples:
broker.c.
pn_proactor_t* pn_proactor ( void  )

Create a proactor.

Must be freed with pn_proactor_free()

Examples:
broker.c, receive.c, and send.c.
int pn_proactor_connect ( pn_proactor_t proactor,
pn_connection_t connection,
const char *  host,
const char *  port 
)

Connect connection to host/port.

Connection and transport events will be returned by pn_proactor_wait()

Parameters
[in]proactorthe proactor object
[in]connectionthe proactor takes ownership, do not free
[in]hostaddress to connect on
[in]portport to connect to
Returns
error on immediate error, e.g. an allocation failure. Other errors are indicated by connection or transport events via pn_proactor_wait()
Examples:
receive.c, and send.c.
void pn_proactor_done ( pn_proactor_t proactor,
pn_event_batch_t events 
)

Call when done handling a batch of events.

Must be called exactly once to match each call to pn_proactor_wait().

Note
Thread-safe: may be called from any thread provided the exactly once rule is respected.
Examples:
broker.c, receive.c, and send.c.
void pn_proactor_free ( pn_proactor_t proactor)

Free the proactor.

Abort any open network connections and clean up all associated resources.

Examples:
broker.c, receive.c, and send.c.
void pn_proactor_interrupt ( pn_proactor_t proactor)

Cause PN_PROACTOR_INTERRUPT to be returned to exactly one call of pn_proactor_wait().

If threads are blocked in pn_proactor_wait(), one of them will be interrupted, otherwise the interrupt will be returned by a future call to pn_proactor_wait(). Calling pn_proactor_interrupt() N times will return PN_PROACTOR_INTERRUPT to N current or future calls of pn_proactor_wait()

Note
Thread-safe.
Examples:
broker.c.
int pn_proactor_listen ( pn_proactor_t proactor,
pn_listener_t listener,
const char *  host,
const char *  port,
int  backlog 
)

Start listening with listener.

pn_proactor_wait() will return a PN_LISTENER_ACCEPT event when a connection can be accepted.

Parameters
[in]proactorthe proactor object
[in]listenerproactor takes ownership of listener, do not free
[in]hostaddress to listen on
[in]portport to listen on
[in]backlognumber of connection requests to queue
Returns
error on immediate error, e.g. an allocation failure. Other errors are indicated by pn_listener_condition() on the PN_LISTENER_CLOSE event.
Examples:
broker.c.
void pn_proactor_set_timeout ( pn_proactor_t proactor,
pn_millis_t  timeout 
)

Cause PN_PROACTOR_TIMEOUT to be returned to a thread calling wait() after timeout milliseconds.

Thread-safe.

Note that calling pn_proactor_set_timeout() again before the PN_PROACTOR_TIMEOUT is delivered will cancel the previous timeout and deliver an event only after the new timeout. pn_proactor_set_timeout(0) will cancel the timeout without setting a new one.

Examples:
send.c.
pn_event_batch_t* pn_proactor_wait ( pn_proactor_t proactor)

Wait for events to handle.

Handle events in the returned batch by calling pn_event_batch_next() until it returns NULL. You must call pn_proactor_done() when you are finished with the batch.

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.

Note
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.
Examples:
broker.c, receive.c, and send.c.