Creates a new pool of VortexChannels.
This module was created to allow having a pool of pre-created channels to be used over and over again during the application life.
Because channel creation and channel close is a expensive process (especially due to all requirements to be meet during channel close) this pool can help to improve greatly your application communication throughput.
Keep in mind the following facts which may help you to chose using vortex channel pool instead of controlling yourself the channels.
If your 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.
BEEP RFC definition says: "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 your applications needs to have a and b message to be independent you'll have to use different channel and those channels must not be waiting for a reply.
To create 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 and then keep on query to use the next channel ready to be used. This notion of "ready to be used" means this channel have no pending replies to be received so if you application send a message it will receive the reply as soon as possible.
Actually the reply can be really late due to remote peer processing but it will not be delayed because previously message 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.
All channel 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.
Finally 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.
|connection ||the session were channels will be created. |
|profile ||the profile the channels will use. |
|max_num ||the number of channels this pool should have. |
|close ||handler to manage channel closing. |
|close_user_data ||user data to be passed in to close handler. |
|received ||handler to manage frame reception on channel. |
|received_user_data ||data to be passed in to received handler. |
|on_channel_pool_created ||a callback to be able to make channel process to be async. |
|user_data ||user data to be passed in to on_channel_created.|
- a newly created VortexChannelPool