pthreadpool: add pthreadpool_cancel_job()
[garming/samba-autobuild/.git] / lib / pthreadpool / pthreadpool.h
index cb8baffebb1825f78cc226fe3a3f19d5e61b1547..dd1f9718b2364ff20dcafe6babf71766fc9f6d32 100644 (file)
@@ -103,4 +103,30 @@ int pthreadpool_destroy(struct pthreadpool *pool);
 int pthreadpool_add_job(struct pthreadpool *pool, int job_id,
                        void (*fn)(void *private_data), void *private_data);
 
+/**
+ * @brief Try to cancel a job in a pthreadpool
+ *
+ * This tries to cancel a job in a pthreadpool. The same
+ * arguments, which were given to pthreadpool_add_job()
+ * needs to be passed.
+ *
+ * The combination of id, fn, private_data might not be unique.
+ * So the function tries to cancel as much matching jobs as possible.
+ * Note once a job is scheduled in a thread it's to late to
+ * cancel it.
+ *
+ * Canceled jobs that weren't started yet won't be reported via a
+ * pool's signal_fn.
+ *
+ * @param[in]  pool            The pool to run the job on
+ * @param[in]  job_id          A custom identifier
+ * @param[in]  fn              The function to run asynchronously
+ * @param[in]  private_data    Pointer passed to fn
+ * @return                     The number of canceled jobs
+ *
+ * @see pthreadpool_add_job()
+ */
+size_t pthreadpool_cancel_job(struct pthreadpool *pool, int job_id,
+                             void (*fn)(void *private_data), void *private_data);
+
 #endif