1.1 --- a/ucx/ucx.h Mon Jul 15 16:59:52 2013 +0200
1.2 +++ b/ucx/ucx.h Wed Jul 17 11:47:02 2013 +0200
1.3 @@ -25,6 +25,12 @@
1.4 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
1.5 * POSSIBILITY OF SUCH DAMAGE.
1.6 */
1.7 +/**
1.8 + * Main UCX Header providing most common definitions.
1.9 + *
1.10 + * @file ucx.h
1.11 + * @author Olaf Wintermann
1.12 + */
1.13
1.14 #ifndef UCX_H
1.15 #define UCX_H
1.16 @@ -39,19 +45,81 @@
1.17 extern "C" {
1.18 #endif
1.19
1.20 +/**
1.21 + * Generic loop statement for lists.
1.22 + *
1.23 + * The first argument is the type of the list and its elements (e.g. UcxList).
1.24 + * The structure invariant of the list must be as follows:
1.25 + * <ul>
1.26 + * <li>a first (non-<code>NULL</code>) element</li>
1.27 + * <li>for each element a reference to the <code>next</code> element (the
1.28 + * variable name of the pointer MUST be <code>next</code>)</li>
1.29 + * <li>the last element of the list MUST have the <code>next</code> pointer
1.30 + * set to <code>NULL</code></li>
1.31 + * </ul>
1.32 + *
1.33 + * The second argument is a pointer to the list. In most cases this will be the
1.34 + * pointer to the first element of the list, but it may also be an arbitrary
1.35 + * element of the list. The iteration will then start with that element.
1.36 + *
1.37 + * The third argument is the name of the iteration variable. The scope of
1.38 + * this variable is limited to the <code>UCX_FOREACH</code> statement.
1.39 + *
1.40 + * @param type The type of <b>both</b> the list and the element
1.41 + * @param list The first element of the list
1.42 + * @param elem The variable name of the element
1.43 + */
1.44 #define UCX_FOREACH(type,list,elem) \
1.45 for (type elem = list ; elem != NULL ; elem = elem->next)
1.46
1.47 -/* element1,element2,custom data -> {-1,0,1} */
1.48 +/**
1.49 + * Function pointer to a compare function.
1.50 + *
1.51 + * The compare function shall take three arguments: the two values that shall be
1.52 + * compared and optional additional data.
1.53 + * The function shall then return -1 if the first argument is less than the
1.54 + * second argument, 1 if the first argument is greater than the second argument
1.55 + * and 0 if both arguments are equal. If the third argument is
1.56 + * <code>NULL</code>, it shall be ignored.
1.57 + */
1.58 typedef int(*cmp_func)(void*,void*,void*);
1.59
1.60 -/* element,custom data -> copy of element */
1.61 +/**
1.62 + * Function pointer to a copy function.
1.63 + *
1.64 + * The copy function shall create a copy of the first argument and may use
1.65 + * additional data provided by the second argument. If the second argument is
1.66 + * <code>NULL</code>, it shall be ignored.
1.67 +
1.68 + * <b>Attention:</b> if pointers returned by functions of this type may be
1.69 + * passed to <code>free()</code> depends on the implementation of the
1.70 + * respective <code>copy_func</code>.
1.71 + */
1.72 typedef void*(*copy_func)(void*,void*);
1.73
1.74 -/* buffer, element size, element count, stream */
1.75 +/**
1.76 + * Function pointer to a write function.
1.77 + *
1.78 + * The signature of the write function shall be compatible to the signature
1.79 + * of standard <code>fwrite</code>, though it may use arbitrary data types for
1.80 + * source and destination.
1.81 + *
1.82 + * The arguments shall contain (in ascending order): a pointer to the source,
1.83 + * the length of one element, the element count, a pointer to the destination.
1.84 + */
1.85 typedef size_t(*write_func)(const void*, size_t, size_t, void*);
1.86
1.87 -/* buffer, element size, element count, stream */
1.88 +/**
1.89 + * Function pointer to a read function.
1.90 + *
1.91 + * The signature of the read function shall be compatible to the signature
1.92 + * of standard <code>fread</code>, though it may use arbitrary data types for
1.93 + * source and destination.
1.94 + *
1.95 + * The arguments shall contain (in ascending order): a pointer to the
1.96 + * destination, the length of one element, the element count, a pointer to the
1.97 + * source.
1.98 + */
1.99 typedef size_t(*read_func)(void*, size_t, size_t, void*);
1.100
1.101 #ifdef __cplusplus
