add more comments and a few missing REQUIREs

lib/isc/task.c

@@ -19,6 +19,11 @@
  * Principal Author: Bob Halley
  */
 
+/*
+ * XXXRTH  Need to document the states a task can be in, and the rules
+ * for changing states.
+ */
+
 #include <config.h>
 
 #include <isc/assertions.h>
@@ -42,7 +47,6 @@
 #define XTHREADTRACE(m)
 #endif
 
-
 /***
  *** Types.
  ***/
@@ -179,16 +183,20 @@ isc_task_create(isc_taskmgr_t *manager, isc_mem_t *mctx, unsigned int quantum,
 }
 
 void
-isc_task_attach(isc_task_t *task, isc_task_t **taskp) {
+isc_task_attach(isc_task_t *source, isc_task_t **targetp) {
 
-	REQUIRE(VALID_TASK(task));
+	/*
-	REQUIRE(taskp != NULL && *taskp == NULL);
+	 * Attach *targetp to source.
+	 */
 
-	LOCK(&task->lock);
+	REQUIRE(VALID_TASK(source));
-	task->references++;
+	REQUIRE(targetp != NULL && *targetp == NULL);
-	UNLOCK(&task->lock);
 
-	*taskp = task;
+	LOCK(&source->lock);
+	source->references++;
+	UNLOCK(&source->lock);
+
+	*targetp = source;
 }
 
 void
@@ -196,6 +204,10 @@ isc_task_detach(isc_task_t **taskp) {
 	isc_boolean_t free_task = ISC_FALSE;
 	isc_task_t *task;
 
+	/*
+	 * Detach *taskp from its task.
+	 */
+
 	REQUIRE(taskp != NULL);
 	task = *taskp;
 	REQUIRE(VALID_TASK(task));
@@ -207,6 +219,13 @@ isc_task_detach(isc_task_t **taskp) {
 	task->references--;
 	if (task->state == task_state_done && task->references == 0)
 		free_task = ISC_TRUE;
+	/*
+	 * XXXRTH  It is currently possible to detach the last
+	 * reference from a task that has not been shutdown.  This
+	 * will prevent the task from being shutdown until the
+	 * task manager is destroyed.  Should there be an
+	 * automatic shutdown on last detach?
+	 */
 	UNLOCK(&task->lock);
 
 	if (free_task)
@@ -218,6 +237,10 @@ isc_task_detach(isc_task_t **taskp) {
 isc_mem_t *
 isc_task_mem(isc_task_t *task) {
 
+	/*
+	 * Get the task's memory context.
+	 */
+
 	REQUIRE(VALID_TASK(task));
 	
 	return (task->mctx);
@@ -230,6 +253,10 @@ isc_task_send(isc_task_t *task, isc_event_t **eventp) {
 	isc_result_t result = ISC_R_SUCCESS;
 	isc_event_t *event;
 
+	/*
+	 * Send '*event' to 'task'.
+	 */
+
 	REQUIRE(VALID_TASK(task));
 	REQUIRE(eventp != NULL);
 	event = *eventp;
@@ -302,11 +329,6 @@ isc_task_send(isc_task_t *task, isc_event_t **eventp) {
 	return (ISC_R_SUCCESS);
 }
 
-unsigned int
-isc_task_purge(isc_task_t *task, void *sender, isc_eventtype_t type) {
-	return (isc_task_purgerange(task, sender, type, type));
-}
-
 unsigned int
 isc_task_purgerange(isc_task_t *task, void *sender, isc_eventtype_t first,
 		    isc_eventtype_t last)
@@ -315,11 +337,16 @@ isc_task_purgerange(isc_task_t *task, void *sender, isc_eventtype_t first,
 	isc_eventlist_t purgeable;
 	unsigned int purge_count;
 
+	/*
+	 * Purge events from a task's event queue.
+	 */
+
 	REQUIRE(VALID_TASK(task));
+	REQUIRE(last >= first);
 
 	/*
-	 * Purge events matching 'sender' and whose type is >= first and
+	 * Events matching 'sender' and whose type is >= first and
-	 * <= last.  sender == NULL means "any sender".
+	 * <= last will be purged.  sender == NULL means "any sender".
 	 *
 	 * Purging never changes the state of the task.
 	 */
@@ -351,10 +378,24 @@ isc_task_purgerange(isc_task_t *task, void *sender, isc_eventtype_t first,
 	return (purge_count);
 }
 
+unsigned int
+isc_task_purge(isc_task_t *task, void *sender, isc_eventtype_t type) {
+
+	/*
+	 * Purge events from a task's event queue.
+	 */
+
+	return (isc_task_purgerange(task, sender, type, type));
+}
+
 isc_result_t
 isc_task_allowsend(isc_task_t *task, isc_boolean_t allowed) {
 	isc_result_t result = ISC_R_SUCCESS;
 
+	/*
+	 * Allow or disallow sending events to 'task'.
+	 */
+
 	REQUIRE(VALID_TASK(task));
 
 	LOCK(&task->lock);
@@ -375,6 +416,10 @@ isc_result_t
 isc_task_allowdone(isc_task_t *task, isc_boolean_t allowed) {
 	isc_result_t result = ISC_R_SUCCESS;
 
+	/*
+	 * Allow or disallow automatic termination of 'task'.
+	 */
+
 	REQUIRE(VALID_TASK(task));
 
 	LOCK(&task->lock);
@@ -402,7 +447,13 @@ isc_task_onshutdown(isc_task_t *task, isc_taskaction_t action, void *arg) {
 	isc_result_t result = ISC_R_SUCCESS;
 	isc_event_t *event;
 
+	/*
+	 * Send a shutdown event with action 'action' and argument 'arg' when
+	 * 'task' is shutdown.
+	 */
+
 	REQUIRE(VALID_TASK(task));
+	REQUIRE(action != NULL);
 
 	event = isc_event_allocate(task->mctx,
 				   NULL,
@@ -436,6 +487,10 @@ isc_task_shutdown(isc_task_t *task) {
 	isc_boolean_t queued_something = ISC_FALSE;
 	isc_event_t *event, *prev;
 
+	/*
+	 * Shutdown 'task'.
+	 */
+
 	REQUIRE(VALID_TASK(task));
 
 	/*
@@ -489,6 +544,10 @@ isc_task_shutdown(isc_task_t *task) {
 void
 isc_task_destroy(isc_task_t **taskp) {
 
+	/*
+	 * Destroy '*taskp'.
+	 */
+
 	REQUIRE(taskp != NULL);
 
 	isc_task_shutdown(*taskp);
@@ -717,6 +776,10 @@ isc_taskmgr_create(isc_mem_t *mctx, unsigned int workers,
 	isc_taskmgr_t *manager;
 	isc_thread_t *threads;
 
+	/*
+	 * Create a new task manager.
+	 */
+
 	REQUIRE(workers > 0);
 	REQUIRE(managerp != NULL && *managerp == NULL);
 
@@ -786,6 +849,10 @@ isc_taskmgr_destroy(isc_taskmgr_t **managerp) {
 	isc_event_t *event, *prev;
 	unsigned int i;
 
+	/*
+	 * Destroy '*managerp'.
+	 */
+
 	REQUIRE(managerp != NULL);
 	manager = *managerp;
 	REQUIRE(VALID_MANAGER(manager));