stuff

libvips/include/vips/threadgroup.h

@@ -39,7 +39,7 @@ extern "C" {
 
 #include <vips/semaphore.h>
 
-/* Stack size for each thread. Need to set this explicitly because some
+/* Stack size for each thread. We need to set this explicitly because some
  * systems have a very low default.
 
  	FIXME ...  should have an environment variable for this?
@@ -50,6 +50,7 @@ extern "C" {
 /* What we track for each thread.
  */
 typedef struct {
+	/*< private >*/
 	REGION *reg;		/* Region this thread operates on */
 	struct im__threadgroup_t *tg; /* Thread group we are part of */
 
@@ -78,6 +79,7 @@ typedef int (*im__work_fn)( im_thread_t *thr,
 /* What we track for a group of threads working together.
  */
 typedef struct im__threadgroup_t {
+	/*< private >*/
 	int zombie;		/* Set if has been freed */
 
 	IMAGE *im;		/* Image we are calculating */
@@ -110,9 +112,9 @@ int im_concurrency_get( void );
 im_threadgroup_t *im_threadgroup_create( IMAGE *im );
 int im_threadgroup_free( im_threadgroup_t *tg );
 im_thread_t *im_threadgroup_get( im_threadgroup_t *tg );
+void im_threadgroup_trigger( im_thread_t *thr );
 void im_threadgroup_wait( im_threadgroup_t *tg );
 int im_threadgroup_iserror( im_threadgroup_t *tg );
-void im_threadgroup_trigger( im_thread_t *thr );
 
 /* Threaded im_prepare()
  */

libvips/iofuncs/threadgroup.c

@@ -13,6 +13,8 @@
  * 15/10/09
  * 	- get rid of inplace and default work stuff, you must now always set a
  * 	  work function
+ * 22/10/09
+ * 	- gtkdoc
  */
 
 /*
@@ -68,6 +70,20 @@
 #include <dmalloc.h>
 #endif /*WITH_DMALLOC*/
 
+/**
+ * SECTION: threadgroup
+ * @short_description: groups of worker threads
+ * @stability: Stable
+ * @see_also: <link linkend="libvips-generate">generate</link>
+ * @include: vips/vips.h
+ *
+ * VIPS has its own threadpool system, used by (for example)
+ * im_prepare_thread().
+ *
+ * Most of this is internal to VIPS and does not need to be documented. You
+ * should only need im_threadgroup_create() and im_threadgroup_free().
+ */
+
 #ifdef TIME_THREAD
 /* Size of time buffers.
  */
@@ -499,7 +515,18 @@ threadgroup_kill_threads( im_threadgroup_t *tg )
 	}
 }
 
-/* Free a threadgroup. Can be called multiple times.
+/**
+ * im_threadgroup_free:
+ * @tg: threadgroup to free
+ *
+ * Frees a threadgroup. This function can be called multiple times, though
+ * only the first time will have any effect.
+ *
+ * All worker threads are terminated and all resources freed.
+ *
+ * See also: im_threadgroup_create().
+ *
+ * Returns: 0.
  */
 int
 im_threadgroup_free( im_threadgroup_t *tg )
@@ -525,7 +552,17 @@ im_threadgroup_free( im_threadgroup_t *tg )
 	return( 0 );
 }
 
-/* Attach a threadgroup to an image.
+/**
+ * im_threadgroup_create:
+ * @im: image to create the threadgroup on
+ *
+ * Makes a threadgroup attached to the image. The threadgroup will be freed
+ * for you if the image is closed, but you can free it yourself with
+ * im_threadgroup_free() if you wish.
+ *
+ * See also: im_threadgroup_free(), im_prepare_thread().
+ *
+ * Returns: an #im_threadgroup_t on success, %NULL on error.
  */
 im_threadgroup_t *
 im_threadgroup_create( IMAGE *im )