axl_bool vortex_connection_ref ( VortexConnection connection,
const char *  who 
)

Increase internal vortex connection reference counting.

Because Vortex Library design, several on going threads shares references to the same connection for several purposes.

Connection reference counting allows to every on going thread to notify the system that connection reference is no longer be used so, if the reference counting reach a zero value, connection resources will be deallocated.

While using the Vortex Library is not required to use this function especially for those applications which are built on top of a profile which is layered on Vortex Library.

This is because connection handling is done through functions such vortex_connection_new and vortex_connection_close (which automatically handles connection reference counting for you).

However, while implementing new profiles these function becomes a key concept to ensure the profile implementation don't get lost connection references.

Keep in mind that using this function implied to use vortex_connection_unref function in all code path implemented. For each call to vortex_connection_ref it should exist a call to vortex_connection_unref. Failing on doing this will cause either memory leak or memory corruption because improper connection deallocations.

The function return axl_true to signal that the connection reference count was increased in one unit. If the function return axl_false, the connection reference count wasn't increased and a call to vortex_connection_unref should not be done. Here is an example:

1 // try to ref the connection
2 if (! vortex_connection_ref (connection, "some known module or file")) {
3  // unable to ref the connection
4  return;
5 }
6 
7 // connection referenced, do work
8 
9 // finally unref the connection
10 vortex_connection_unref (connection, "some known module or file");
Parameters
connectionthe connection to operate.
whowho have increased the reference.
Returns
axl_true if the connection reference was increased or axl_false if an error was found.

References vortex_connection_ref_internal().

Referenced by vortex_alive_enable_check(), vortex_channel_new_full(), vortex_connection_close(), vortex_connection_foreach_channel(), and vortex_listener_shutdown().