From 3ee98f3bac24fd1c70a9de3e0fbe774e762c25b3 Mon Sep 17 00:00:00 2001 From: Tavian Barnes Date: Fri, 26 Jun 2009 15:31:34 +0000 Subject: Add lots of comments, and some code fixes discovered in the process. --- libdimension/dimension/progress.h | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'libdimension/dimension/progress.h') diff --git a/libdimension/dimension/progress.h b/libdimension/dimension/progress.h index a865c8f..7958ab9 100644 --- a/libdimension/dimension/progress.h +++ b/libdimension/dimension/progress.h @@ -18,6 +18,13 @@ * . * *************************************************************************/ +/* + * An interface for asynchronous tasks. *_async() versions of functions + * return a dmnsn_progress* object which can indicate the progress of the + * background task, and wait for task completion. The task's return value + * is returned as an int from dmnsn_finish_progress(). + */ + #ifndef DIMENSION_PROGRESS_H #define DIMENSION_PROGRESS_H @@ -43,6 +50,7 @@ typedef struct { } dmnsn_progress; dmnsn_progress *dmnsn_new_progress(); +/* For failed returns from *_async() functions */ void dmnsn_delete_progress(dmnsn_progress *progress); /* This joins the worker thread and returns it's integer return value in @@ -50,10 +58,14 @@ void dmnsn_delete_progress(dmnsn_progress *progress); int dmnsn_finish_progress(dmnsn_progress *progress); double dmnsn_get_progress(const dmnsn_progress *progress); +/* Wait for the progress to be >= prog, in a better way than spinlocking */ void dmnsn_wait_progress(const dmnsn_progress *progress, double prog); +/* Create a new level of loop nesting */ void dmnsn_new_progress_element(dmnsn_progress *progress, unsigned int total); +/* Increment the progress counter; should only be called from innermost loop */ void dmnsn_increment_progress(dmnsn_progress *progress); -void dmnsn_progress_done(dmnsn_progress *progress); +/* Instantly complete the progress */ +void dmnsn_done_progress(dmnsn_progress *progress); #endif /* DIMENSION_PROGRESS_H */ -- cgit v1.2.3