Merged revisions 108227 via svnmerge from

https://origsvn.digium.com/svn/asterisk/branches/1.4

........
r108227 | mmichelson | 2008-03-12 16:16:28 -0500 (Wed, 12 Mar 2008) | 12 lines

Added a large comment before the AST_SCHED_DEL macro to explain its purpose as well as when
it is appropriate and when it is not appropriate to use it.

I also removed the part of the debug message that mentions that this is probably a bug because
there are some perfectly legitimate places where ast_sched_del may fail to delete an entry (e.g.
when the scheduler callback manually reschedules with a new id instead of returning non-zero to
tell the scheduler to reschedule with the same idea). I also raised the debug level of the debug
message in AST_SCHED_DEL since it seems like it could come up quite frequently since the macro
is probably being used in several places where it shouldn't be. Also removed the redundant line,
file, and function information since that is provided by ast_log.


........


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@108238 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 19 insertions, 1 deletions

diff --git a/include/asterisk/sched.h b/include/asterisk/sched.h
index 28a14b847..3978e3299 100644
--- a/include/asterisk/sched.h
+++ b/include/asterisk/sched.h
@@ -35,6 +35,24 @@ extern "C" {
  */
 #define SCHED_MAX_CACHE 128
 
+/*! \brief a loop construct to ensure that
+ * the scheduled task get deleted. The idea is that
+ * if we loop attempting to remove the scheduled task,
+ * then whatever callback had been running will complete
+ * and reinsert the task into the scheduler.
+ *
+ * Note that this is NOT always appropriate. This should 
+ * only be used for tasks whose callback may return non-zero 
+ * to indicate that the task needs to be rescheduled with the
+ * SAME id as previously.
+ *
+ * Some scheduler callbacks instead may reschedule the task themselves,
+ * thus removing the previous task id from the queue. If the task is rescheduled
+ * in this manner, then the id for the task will be different than before
+ * and so it makes no sense to use this macro. Note that if using the scheduler
+ * in this manner, it is perfectly acceptable for ast_sched_del to fail, and this
+ * macro should NOT be used.
+ */
 #define AST_SCHED_DEL(sched, id) \
 	do { \
 		int _count = 0; \
@@ -42,7 +60,7 @@ extern "C" {
 			usleep(1); \
 		} \
 		if (_count == 10) \
-			ast_log(LOG_DEBUG, "Unable to cancel schedule ID %d.  This is probably a bug (%s: %s, line %d).\n", id, __FILE__, __PRETTY_FUNCTION__, __LINE__); \
+			ast_debug(3, "Unable to cancel schedule ID %d.\n", id); \
 		id = -1; \
 	} while (0);