Update of /usr/cvsroot/asterisk/include/asterisk
In directory mongoose.digium.com:/tmp/cvs-serv12155/include/asterisk
Modified Files:
channel.h
Log Message:
document locking rules for spy API functions
Index: channel.h
===================================================================
RCS file: /usr/cvsroot/asterisk/include/asterisk/channel.h,v
retrieving revision 1.109
retrieving revision 1.110
diff -u -d -r1.109 -r1.110
--- channel.h 28 Oct 2005 23:01:13 -0000 1.109
+++ channel.h 1 Nov 2005 15:28:01 -0000 1.110
@@ -1042,6 +1042,9 @@
\param chan The channel to add the spy to.
\param spy A pointer to ast_channel_spy structure describing how the spy is
to be used.
\return 0 for success, non-zero for failure
+
+ Note: This function performs no locking; you must hold the channel's lock
before
+ calling this function.
*/
int ast_channel_spy_add(struct ast_channel *chan, struct ast_channel_spy *spy);
@@ -1050,6 +1053,9 @@
\param chan The channel to remove the spy from
\param spy The spy to be removed
\return nothing
+
+ Note: This function performs no locking; you must hold the channel's lock
before
+ calling this function.
*/
void ast_channel_spy_remove(struct ast_channel *chan, struct ast_channel_spy
*spy);
@@ -1058,6 +1064,9 @@
\param chan The channel to operate on
\param type A character string identifying the type of spies to be stopped
\return nothing
+
+ Note: This function performs no locking; you must hold the channel's lock
before
+ calling this function.
*/
void ast_channel_spy_stop_by_type(struct ast_channel *chan, const char *type);
@@ -1071,6 +1080,9 @@
due to mismatched queue lengths, or if the spy structure is configured to
return
unmixed audio (in which case each call to this function will return a frame
of audio
from each side of channel).
+
+ Note: This function performs no locking; you must hold the spy's lock before
calling
+ this function. You must <b>not</b> hold the channel's lock at the same time.
*/
struct ast_frame *ast_channel_spy_read_frame(struct ast_channel_spy *spy,
unsigned int samples);
@@ -1078,6 +1090,12 @@
\brief Efficiently wait until audio is available for a spy, or an exception
occurs.
\param spy The spy to wait on
\return nothing
+
+ Note: The locking rules for this function are non-obvious... first, you must
<b>not</b>
+ hold the channel's lock when calling this function. Second, you must hold
the spy's lock
+ before making the function call; while the function runs the lock will be
released, and
+ when the trigger event occurs, the lock will be re-obtained. This means that
when control
+ returns to your code, you will again hold the spy's lock.
*/
void ast_channel_spy_trigger_wait(struct ast_channel_spy *spy);
_______________________________________________
Asterisk-Cvs mailing list
[email protected]
http://lists.digium.com/mailman/listinfo/asterisk-cvs
