From: lurchi <lurchi@strangeplace.net>
Date: Fri, 25 Aug 2017 10:59:28 +0000 (+0200)
Subject: clarify documentation about adding / deleting tasks
X-Git-Tag: gnunet-0.11.0rc0~48^2^2~6
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=909c769cc09296f8abccf2a5ee6a6a687b4efc3a;p=oweals%2Fgnunet.git

clarify documentation about adding / deleting tasks
---

diff --git a/src/include/gnunet_scheduler_lib.h b/src/include/gnunet_scheduler_lib.h
index 119f3c8ed..b6f127f0c 100644
--- a/src/include/gnunet_scheduler_lib.h
+++ b/src/include/gnunet_scheduler_lib.h
@@ -216,7 +216,8 @@ struct GNUNET_SCHEDULER_TaskContext
 
 /**
  * Function used by event-loop implementations to signal the scheduler
- * that a particular @a task is ready due to an event of type @a et.
+ * that a particular @a task is ready due to an event specified in the
+ * et field of @a fdi.
  *
  * This function will then queue the task to notify the application
  * that the task is ready (with the respective priority).
@@ -268,8 +269,11 @@ struct GNUNET_SCHEDULER_Driver
   void *cls;
 
   /**
-   * Add a @a task to be run if the conditions given
-   * in @a fdi are satisfied.
+   * Add a @a task to be run if the conditions specified in the 
+   * et field of the given @a fdi are satisfied. The et field will
+   * be cleared after this call and the driver is expected to set
+   * the type of the actual event before passing @a fdi to
+   * #GNUNET_SCHEDULER_task_ready.
    *
    * @param cls closure
    * @param task task to add
@@ -283,18 +287,18 @@ struct GNUNET_SCHEDULER_Driver
          struct GNUNET_SCHEDULER_FdInfo *fdi);
 
   /**
-   * Delete a @a task from the set of tasks to be run.
+   * Delete a @a task from the set of tasks to be run. A task may
+   * comprise multiple FdInfo entries previously added with the add
+   * function. The driver is expected to delete them all.
    *
    * @param cls closure
    * @param task task to delete
-   * @param fdi conditions to watch for (must match @e add call)
    * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
-   *   (i.e. @a task or @a fdi do not match prior @e add call)
+   *   (i.e. @a task does not match prior @e add call)
    */
   int
   (*del)(void *cls,
-	 struct GNUNET_SCHEDULER_Task *task,
-	 struct GNUNET_SCHEDULER_FdInfo *fdi);
+	 struct GNUNET_SCHEDULER_Task *task);
 
   /**
    * Set time at which we definitively want to get a wakeup call.
diff --git a/src/util/scheduler.c b/src/util/scheduler.c
index 32916d99d..ac9494fa0 100644
--- a/src/util/scheduler.c
+++ b/src/util/scheduler.c
@@ -1829,12 +1829,13 @@ GNUNET_SCHEDULER_add_select (enum GNUNET_SCHEDULER_Priority prio,
 
 /**
  * Function used by event-loop implementations to signal the scheduler
- * that a particular @a task is ready due to an event of type @a et.
+ * that a particular @a task is ready due to an event specified in the
+ * et field of @a fdi.
  *
  * This function will then queue the task to notify the application
  * that the task is ready (with the respective priority).
  *
- * @param task the task that is ready, NULL for wake up calls
+ * @param task the task that is ready
  * @param fdi information about the related FD
  */
 void