Raw connection

Unsettled API - An API allowing raw sockets to be used with proactor More...

Classes
struct	pn_raw_buffer_t
	A descriptor used to represent a single raw buffer in memory. More...

Typedefs
typedef struct pn_raw_connection_t	pn_raw_connection_t
	A raw network connection used with the proactor.

Functions
PNP_EXTERN pn_raw_connection_t *	pn_raw_connection (void)
	Create a new raw connection for use with the Proactor.
PNP_EXTERN const struct pn_netaddr_t *	pn_raw_connection_local_addr (pn_raw_connection_t *connection)
	Get the local address of a raw connection.
PNP_EXTERN const struct pn_netaddr_t *	pn_raw_connection_remote_addr (pn_raw_connection_t *connection)
	Get the local address of a raw connection.
PNP_EXTERN void	pn_raw_connection_close (pn_raw_connection_t *connection)
	Close a raw connection.
PNP_EXTERN void	pn_raw_connection_read_close (pn_raw_connection_t *connection)
	Shutdown a raw connection for reading.
PNP_EXTERN void	pn_raw_connection_write_close (pn_raw_connection_t *connection)
	Shutdown a raw connection for writing.
PNP_EXTERN size_t	pn_raw_connection_read_buffers_capacity (pn_raw_connection_t *connection)
	Query the raw connection for how many more read buffers it can be given.
PNP_EXTERN size_t	pn_raw_connection_write_buffers_capacity (pn_raw_connection_t *connection)
	Query the raw connection for how many more write buffers it can be given.
PNP_EXTERN size_t	pn_raw_connection_give_read_buffers (pn_raw_connection_t *connection, pn_raw_buffer_t const *buffers, size_t num)
	Give the raw connection buffers to use for reading from the underlying socket.
PNP_EXTERN size_t	pn_raw_connection_take_read_buffers (pn_raw_connection_t *connection, pn_raw_buffer_t *buffers, size_t num)
	Fetch buffers with bytes read from the raw socket.
PNP_EXTERN size_t	pn_raw_connection_write_buffers (pn_raw_connection_t *connection, pn_raw_buffer_t const *buffers, size_t num)
	Give the raw connection buffers to write to the underlying socket.
PNP_EXTERN size_t	pn_raw_connection_take_written_buffers (pn_raw_connection_t *connection, pn_raw_buffer_t *buffers, size_t num)
	Return a buffer chain with buffers that have all been written to the raw socket.
PNP_EXTERN bool	pn_raw_connection_is_read_closed (pn_raw_connection_t *connection)
	Is connection closed for read?
PNP_EXTERN bool	pn_raw_connection_is_write_closed (pn_raw_connection_t *connection)
	Is connection closed for write?
PNP_EXTERN void	pn_raw_connection_wake (pn_raw_connection_t *connection)
	Return a PN_RAW_CONNECTION_WAKE event for connection as soon as possible.
PNP_EXTERN pn_condition_t *	pn_raw_connection_condition (pn_raw_connection_t *connection)
	Get additional information about a raw connection error.
PNP_EXTERN void *	pn_raw_connection_get_context (pn_raw_connection_t *connection)
	Get the application context associated with this raw connection.
PNP_EXTERN void	pn_raw_connection_set_context (pn_raw_connection_t *connection, void *context)
	Set a new application context for a raw connection.
PNP_EXTERN pn_record_t *	pn_raw_connection_attachments (pn_raw_connection_t *connection)
	Get the attachments that are associated with a raw connection.
PNP_EXTERN pn_raw_connection_t *	pn_event_raw_connection (pn_event_t *event)
	Return the raw connection associated with an event.
PNP_EXTERN pn_raw_connection_t *	pn_event_batch_raw_connection (pn_event_batch_t *batch)
	Query the batch for the subject of the batch.

Detailed Description

Unsettled API - An API allowing raw sockets to be used with proactor

---

Class Documentation

pn_raw_buffer_t

struct pn_raw_buffer_t

A descriptor used to represent a single raw buffer in memory.

Note

The intent of the offset is to allow the actual bytes being read/written to be at a variable location relative to the head of the buffer because of other data or structures that are important to the application associated with the data to be written but not themselves read/written to the connection.

For read buffers: When read buffers are returned to the application size will be the number of bytes read. Read operations will not change the context, bytes or capacity members of the structure.

For write buffers: When write buffers are returned to the application all of the struct members will be returned unaltered. Also write operations will not modify the bytes of the buffer passed in at all. In principle this means that the write buffer can be used for multiple writes at the same time as long as the actual buffer is unmodified by the application at any time the buffer is being used by any raw connection.

Class Members
uintptr_t	context	Used to associate arbitrary application data with this raw buffer.
char *	bytes	Pointer to the start of the raw buffer, if this is null then no buffer is represented.
uint32_t	capacity	Count of available bytes starting at bytes.
uint32_t	size	Number of bytes read or to be written starting at offset.
uint32_t	offset	First byte in the buffer to be read or written.

Function Documentation

pn_raw_connection()

PNP_EXTERN pn_raw_connection_t * pn_raw_connection

(

void

)

Create a new raw connection for use with the Proactor.

See pn_proactor_raw_connect and pn_listener_raw_accept.

Returns

A newly allocated pn_raw_connection_t or NULL if there wasn't sufficient memory.

Note

This is the only pn_raw_connection_t function that allocates memory. So an application that wants good control of out of memory conditions should check the return value for NULL.

It would be a good practice is to create a raw connection and attach application specific context to it before giving it to the proactor.

There is no way to free a pn_raw_connection_t as once passed to the proactor the proactor owns it and controls its lifecycle.

pn_raw_connection_local_addr()

PNP_EXTERN const struct pn_netaddr_t * pn_raw_connection_local_addr

(

pn_raw_connection_t *

connection

)

Get the local address of a raw connection.

Return NULL if not available. Pointer is invalid after the transport closes (PN_RAW_CONNECTION_DISCONNECTED event is handled)

pn_raw_connection_remote_addr()

PNP_EXTERN const struct pn_netaddr_t * pn_raw_connection_remote_addr

(

pn_raw_connection_t *

connection

)

Get the local address of a raw connection.

Return NULL if not available. Pointer is invalid after the transport closes (PN_RAW_CONNECTION_DISCONNECTED event is handled)

pn_raw_connection_close()

PNP_EXTERN void pn_raw_connection_close

(

pn_raw_connection_t *

connection

)

Close a raw connection.

This will flush any buffers to be written; close the underlying socket and release all buffers held by the raw connection.

It will cause PN_RAW_CONNECTION_READ and PN_RAW_CONNECTION_WRITTEN to be emitted so the application can clean up buffers given to the raw connection. After that a PN_RAW_CONNECTION_DISCONNECTED event will be emitted to allow the application to clean up any other state held by the raw connection.

pn_raw_connection_read_close()

PNP_EXTERN void pn_raw_connection_read_close

(

pn_raw_connection_t *

connection

)

Shutdown a raw connection for reading.

This will close the underlying socket for reading and release all empty read buffers held by the raw connection.

It will cause PN_RAW_CONNECTION_READ to be emitted so the application can clean up buffers given to the raw connection. Note that these buffers may still also contain data read from the socket but not yet consumed by the application.

If pn_raw_connection_write_close() has already been called then PN_RAW_CONNECTION_DISCONNECTED will then also be emitted.

In order to fully close a raw connection the application will need to either call pn_raw_connection_close() or pn_raw_connection_write_close() after it calls pn_raw_connection_read_close().

pn_raw_connection_write_close()

PNP_EXTERN void pn_raw_connection_write_close

(

pn_raw_connection_t *

connection

)

Shutdown a raw connection for writing.

This will flush any buffers to be written to the socket; close the underlying socket for writing and release all write buffers held by the raw connection.

It will cause PN_RAW_CONNECTION_WRITTEN to be emitted so the application can clean up write buffers given to the raw connection.

If pn_raw_connection_read_close() has already been called then PN_RAW_CONNECTION_DISCONNECTED will then also be emitted.

In order to fully close a raw connection the application will need to either call pn_raw_connection_close() or pn_raw_connection_read_close() after it calls pn_raw_connection_write_close().

pn_raw_connection_give_read_buffers()

PNP_EXTERN size_t pn_raw_connection_give_read_buffers	(	pn_raw_connection_t *	connection,
		pn_raw_buffer_t const *	buffers,
		size_t	num
	)

Give the raw connection buffers to use for reading from the underlying socket.

If the raw socket has no read buffers then the application will never receive a PN_RAW_CONNECTION_READ event.

A PN_RAW_CONNECTION_NEED_READ_BUFFERS event will be generated immediately after the PN_RAW_CONNECTION_CONNECTED event if there are no read buffers. It will also be generated whenever the raw connection runs out of read buffers. In both these cases the event will not be generated again until pn_raw_connection_give_read_buffers is called.

Returns

the number of buffers actually given to the raw connection. This will only be different from the number supplied if the connection has no more space to record more buffers. In this case the buffers taken will be the earlier buffers in the array supplied, the elements 0 to the returned value-1.

Note

The buffers given to the raw connection are owned by it until the application receives the buffers back with a pn_raw_connection_take_read_buffers call. They must not be accessed at all (written or even read) from calling pn_raw_connection_give_read_buffers until receiving them back.

The application should not assume that the PN_RAW_CONNECTION_NEED_READ_BUFFERS event signifies that the connection is readable.

pn_raw_connection_take_read_buffers()

PNP_EXTERN size_t pn_raw_connection_take_read_buffers	(	pn_raw_connection_t *	connection,
		pn_raw_buffer_t *	buffers,
		size_t	num
	)

Fetch buffers with bytes read from the raw socket.

The buffers will be placed in the buffers array in the order in which they were read. So the first buffer in the array will contain the first bytes read; the second buffer the next bytes etc.

Parameters

[out]	buffers	pointer to an array of pn_raw_buffer_t structures which will be filled in with the read buffer information
[in]	num	the number of buffers allocated in the passed in array of buffers

Returns

the number of buffers being returned, if there are no read bytes then this will be 0. As many buffers will be returned as can be given the number that are passed in. So if the number returned is less than the number passed in there are no more buffers read. But if the number is the same there may be more read buffers to take.

Note

After the application receives PN_RAW_CONNECTION_READ there should be bytes read from the socket and hence this call should return buffers. It is safe to carry on calling pn_raw_connection_take_read_buffers until it returns 0.

pn_raw_connection_write_buffers()

PNP_EXTERN size_t pn_raw_connection_write_buffers	(	pn_raw_connection_t *	connection,
		pn_raw_buffer_t const *	buffers,
		size_t	num
	)

Give the raw connection buffers to write to the underlying socket.

The buffers will be written to the connection in the order that they are passed in. That is the first buffer in the array of buffers passed will be the first buffer written to the connection; the second buffer passed in will be the second written etc.

A PN_RAW_CONNECTION_WRITTEN event will be generated once the buffers have been written to the socket until this point the buffers must not be accessed at all (written or even read).

A PN_RAW_CONNECTION_NEED_WRITE_BUFFERS event will be generated immediately after the PN_RAW_CONNECTION_CONNECTED event if there are no write buffers. It will also be generated whenever the raw connection finishes writing all the write buffers. In both these cases the event will not be generated again until pn_raw_connection_write_buffers is called.

Returns

the number of buffers actually recorded by the raw connection to write. This will only be different from the number supplied if the connection has no more space to record more buffers. In this case the buffers recorded will be the earlier buffers in the array supplied, the elements 0 to the returned value-1.

pn_raw_connection_take_written_buffers()

PNP_EXTERN size_t pn_raw_connection_take_written_buffers	(	pn_raw_connection_t *	connection,
		pn_raw_buffer_t *	buffers,
		size_t	num
	)

Return a buffer chain with buffers that have all been written to the raw socket.

Parameters

[out]	buffers	pointer to an array of pn_raw_buffer_t structures which will be filled in with the written buffer information
[in]	num	the number of buffers allocated in the passed in array of buffers

Returns

the number of buffers being returned, if there is are no written buffers to return then this will be 0. As many buffers will be returned as can be given the number that are passed in. So if the number returned is less than the number passed in there are no more buffers written. But if the number is the same there may be more written buffers to take.

Note

After the application receives PN_RAW_CONNECTION_WRITTEN there should be bytes written to the socket and hence this call should return buffers. It is safe to carry on calling pn_raw_connection_take_written_buffers until it returns 0.

The buffers will be returned in the same order as they were originally passed in.

pn_raw_connection_is_read_closed()

PNP_EXTERN bool pn_raw_connection_is_read_closed

(

pn_raw_connection_t *

connection

)

Is connection closed for read?

Returns

true if the raw connection is closed for read.

pn_raw_connection_is_write_closed()

PNP_EXTERN bool pn_raw_connection_is_write_closed

(

pn_raw_connection_t *

connection

)

Is connection closed for write?

Returns

true if the raw connection is closed for write.

pn_raw_connection_wake()

PNP_EXTERN void pn_raw_connection_wake

(

pn_raw_connection_t *

connection

)

Return a PN_RAW_CONNECTION_WAKE event for connection as soon as possible.

At least one wake event will be returned, serialized with other Proactor events for the same raw connection, except as noted. Wakes can be "coalesced" - if several pn_raw_connection_wake() calls happen close together, there may be only one PN_RAW_CONNECTION_WAKE event that occurs after all of them.

A PN_RAW_CONNECTION_WAKE event will never follow a PN_RAW_CONNECTION_DISCONNECTED event. I.e. it will be dropped.

The result of this call is undefined if called after a PN_RAW_CONNECTION_DISCONNECTED event has been delivered and its event batch has been released by a call to pn_proactor_done(). It is also undefined if called before the return of either pn_proactor_raw_connect() or pn_listener_raw_accept() for client or server raw connections respectively.

Note

Thread-safe

pn_raw_connection_condition()

PNP_EXTERN pn_condition_t * pn_raw_connection_condition

(

pn_raw_connection_t *

connection

)

Get additional information about a raw connection error.

There is a raw connection error if the PN_RAW_CONNECTION_DISCONNECTED event is received and the pn_condition_t associated is non null (

See also

pn_condition_is_set).

The value returned is only valid until the end of handler for the PN_RAW_CONNECTION_DISCONNECTED event.

pn_raw_connection_get_context()

PNP_EXTERN void * pn_raw_connection_get_context

(

pn_raw_connection_t *

connection

)

Get the application context associated with this raw connection.

The application context for a raw connection may be set using pn_raw_connection_set_context.

Parameters

[in]

connection

the raw connection whose context is to be returned.

Returns

the application context for the raw connection

pn_raw_connection_set_context()

PNP_EXTERN void pn_raw_connection_set_context	(	pn_raw_connection_t *	connection,
		void *	context
	)

Set a new application context for a raw connection.

The application context for a raw connection may be retrieved using pn_raw_connection_get_context.

Parameters

[in]	connection	the raw connection object
[in]	context	the application context

pn_event_raw_connection()

PNP_EXTERN pn_raw_connection_t * pn_event_raw_connection

(

pn_event_t *

event

)

Return the raw connection associated with an event.

Returns

NULL if the event is not associated with a raw connection.

pn_event_batch_raw_connection()

PNP_EXTERN pn_raw_connection_t * pn_event_batch_raw_connection

(

pn_event_batch_t *

batch

)

Query the batch for the subject of the batch.

If it is a raw connection then it is returned. NULL means the subject of the batch is not a raw connection. The returned raw connection is valid until pn_proactor_done() is called again on the same batch.

Returns

the raw connection that is subject of the batch or NULL if none.