refactoring + documentation + testing + added Map and Refcount

[dragonstd.git] / flag.h

diff --git a/flag.h b/flag.h
index 61e0be20ac472ddf3589b7145f0b479786c11871..78c5ac14e91b51d58f7e4ac46bf666e0c5776cf0 100644 (file)
--- a/flag.h
+++ b/flag.h
@@ -1,19 +1,61 @@
-#ifndef _DRAGONSTD_FLAG_H_
+/*
+       Flag
+       ----
+
+       A flag is a data structure that can be used to syncronize a boolean across multiple
+               threads.
+
+       The flag's state can be set, read and waited for in a thread safe manner.
+*/
+
+#ifndef _DRAGONSTD_FLAG_H_ // include guard
 #define _DRAGONSTD_FLAG_H_
 
-#include <stdbool.h>
-#include <stdatomic.h>
-#include <pthread.h>
+#include <pthread.h>   // for pthread_mutex_t, pthread_cond_t
+#include <stdatomic.h> // for atomic_bool
+#include <stdbool.h>   // for bool
 
 typedef struct {
-       atomic_bool done;
-       pthread_cond_t cv;
-       pthread_mutex_t mtx;
+       /* protected */
+       atomic_bool set;     // whether the flag is set
+       /* private */
+       pthread_cond_t cnd;  // condition variable used for waiting
+       pthread_mutex_t mtx; // mutex to protect the condition variable
 } Flag;
 
-Flag *flag_create();
-void flag_delete(Flag *flag);
+void flag_ini(Flag *flag);
+/*
+       Initializes the flag.
+
+       The flag should be uninitialized or deleted before passed to this function.
+       This function should be called before any other function is called on the flag.
+*/
+
+void flag_dst(Flag *flag);
+/*
+       Destroy the flag.
+
+       The refcount is unusable until reinitialized afterwards.
+*/
+
 void flag_set(Flag *flag);
-void flag_wait(Flag *flag);
+/*
+       [Thread Safe]
+       Sets the flag.
+
+       This changes the flag state to be true and wakes up any threads waiting for it.
+       Afterwards, **the state cannot be changed back**.
+
+       This function can be called multiple times.
+*/
+
+void flag_slp(Flag *flag);
+/*
+       [Thread Safe]
+       Waits for the flag to be true.
+
+       This will sleep until the flag's state is changed to true, unless it is already set to
+               true.
+*/
 
-#endif
+#endif // _DRAGONSTD_FLAG_H_