[Vortex] doc+api comments on vortex_connection_new and vortex_channel_new

[Francis Brosnan Blazquez]

El dom, 29-10-2006 a las 09:10 -0800, Sam Roberts escribió:
> Hi Francis,

Hi Sam,

> Doc comment:
> 
> They don't return a connection or channel object if the on_connected
> or
> on_channel_created callbacks are provided. I hadn't realized this from
> reading the docs, its kindof implied, but not outright stated!

Ok. I've updated Vortex documentation about return value from:

"a new VortexConnection. You should use vortex_connection_is_ok to check
if you have already connected."

To:

"A newly created VortexConnection if called in a blocking manner, that
is, without providing the on_connected handler. If you provide the
on_connected handler, the function will return NULL, and the connection
created will be notified on the handler on_connected. In both cases, you
must use vortex_connection_is_ok to check if you are already connected."


> API comment:
> 
> VortexOnCloseChannel ... must return true/false, so is not so useful
> if you have to post it's result to a new thread, where the decision to
> allow close or not will be made.
> 
> Can it NOT return? Will that block other threads?

No, it can't. Currently, close channel notification is done in a way
that it requires the handler provided by the user (VortexOnCloseChannel)
to return with the reply. If it doesn't returns, it will block the
thread running that handler, causing a problem if several close request
are received.

Maybe, the close handling could be splitted into the notification piece
and the reply piece, allowing the user space to get a close notification
and just return, and then the user space must call to notify its
intention about closing the channel or not. Are you looking for
something like this or I missing something?

Thanks for the comments Sam!

> Cheers,
> Sam
> 
> 
-- 
Francis Brosnan Blazquez <francis at aspl.es>
Advanced Software Production Line, S.L.