VortexChannelPool* vortex_channel_pool_new ( VortexConnection connection,
const char *  profile,
int  init_num,
VortexOnCloseChannel  close,
axlPointer  close_user_data,
VortexOnFrameReceived  received,
axlPointer  received_user_data,
VortexOnChannelPoolCreated  on_channel_pool_created,
axlPointer  user_data 
)

Creates a new pool of VortexChannel items, that are managed in a way that ensure better throutput relation.

This module was created to allow having a pool of pre-created channels (VortexChannel) to be used over and over again during the application life.

Because channel creation and channel close is an expensive process (especially due to all requirements to be meet during channel close), the channel pool can help to improve greatly your application communication throughput, considering the relation between request/replies received on a selected connection (VortexConnection).

Keep in mind the following facts which may help you to chose using vortex channel pool instead of controlling yourself channels created on a particular connection.

  • If an application needs to not be blocked while sending messages you have to use a new channel or a channel that is not waiting for a reply, so new messages (requests) are not blocked by replies for previous messages (requests).

    BEEP RFC definition states: "any message sent will be delivered in order at the remote peer and remote peer must reply the message receive in the same order."

    As a consequence, if message a and b are sent over channel 1, the message reply for b won't be received until message reply for a is received.

    In other words, if your applications needs to have a and b message to be managed independently, you'll have to use different channel, making each interaction to be independent, and those channels must not be waiting for a previous reply (vortex_channel_is_ready).

  • To start a channel needs two message to be exchanged between peers and, of course, the channel creation can be denied by remote peer. This have a considerable overhead.

  • To close a channel needs two message to be exchanged between peers and remote peers may accept channel to be closed at any time. This is not only a overhead problem but also great performance impact problem if your application close channels frequently.

The VortexChannelPool allows you to create a pool of channels and reuse then on next operations, saving starts/close operations, based on the readyness of channels inside the pool.

This notion of "ready to be used" means that the channel have no pending replies to be received so if you application send a message it will receive the reply as soon as possible (vortex_channel_is_ready).

Actually the reply can be really late due to remote peer processing but it will not be delayed by messages previously sent, awaiting for replies.

Once you create a pool you can get its actual size, add or remove channel from the pool or attach new channel that weren't created by this module. In general, we can consider that there are two ways to use the channel pool once created:

  • Allow the channel pool to manage the channel creation (setting all data to be used at this function: start handler, frame received, etc..). In this context you must use the following function to add and remove channels to the pool:

  • In the case that the channel creation is too complex or the application level wants to control the channel creation process, you must use the following functions to add channels to the pool:

    This method have a problem: automatic channel creation is not activated. The channel pool could react by adding more channels if a channel is requested but no channel is available (vortex_channel_pool_get_next_ready).

In the case that channel creation process is managed by the channel pool, all of them will be created over the given session (connection) and will be created under the semantics defined by profile. The function will block you until all channels are created. During the channel creation process one channel may fail to be created so you should check how many channels have been really created.

You can create several channel pools over the same connection. Every channel pool is identified by an id. This Id can be used to lookup certain channel pool into a given connection.

Once a channel pool is created, it is associated with the given connection so calls to vortex_connection_get_channel_pool over a connection will return the pool created. You can of course hold a reference to your channel pool and avoid using previous function.

The function vortex_channel_pool_get_next_ready will return the next channel ready to be used. But this function may return NULL if no channel is ready to be used. You can optionally set the auto_inc parameter to increase channel pool size to resolve your petition.

Once the channel retreived from the channel pool is no longer required, it is "returned to the channel pool", to be usable by other queries, by calling to vortex_channel_pool_release_channel.

See this section which contains more information about using the channel pool: 3.2 Implementing the request-response pattern.

Parameters
connectionThe session were channels will be created.
profileThe profile the channels will use.
init_numThe number of channels this pool will create at the startup.
closeHandler to manage channel closing.
close_user_dataUser data to be passed in to close handler.
receivedHandler to manage frame reception on channel.
received_user_dataData to be passed in to received handler.
on_channel_pool_createdA callback to be able to make channel process to be async.
user_dataUser data to be passed in to on_channel_created.
Returns
A newly created VortexChannelPool. The reference returned is already attached to the VortexConnection provided so, it is not required to release it. In the case the on_channel_pool_created handler is provided, the function returns NULL, and the channel pool reference is notified at the handler. Memory deallocation for the reference returned will be produced once the connection associated to it is deallocated.

References vortex_channel_pool_new_full().