ucx: ucx/ucx.h@5a0859739b76

     1 /*

     2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

     3  *

     4  * Copyright 2013 Olaf Wintermann. All rights reserved.

     5  *

     6  * Redistribution and use in source and binary forms, with or without

     7  * modification, are permitted provided that the following conditions are met:

     8  *

     9  *   1. Redistributions of source code must retain the above copyright

    10  *      notice, this list of conditions and the following disclaimer.

    11  *

    12  *   2. Redistributions in binary form must reproduce the above copyright

    13  *      notice, this list of conditions and the following disclaimer in the

    14  *      documentation and/or other materials provided with the distribution.

    15  *

    16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

    17  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

    18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

    19  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE

    20  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

    21  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

    22  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

    23  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN

    24  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

    25  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE

    26  * POSSIBILITY OF SUCH DAMAGE.

    27  */

    28 /**

    29  * Main UCX Header providing most common definitions.

    30  *

    31  * @file   ucx.h

    32  * @author Olaf Wintermann

    33  */

    35 #ifndef UCX_H

    36 #define	UCX_H

    38 #include <stdlib.h>

    40 #ifdef	__cplusplus

    41 #ifndef _Bool

    42 #define _Bool bool

    43 #define restrict

    44 #endif

    45 extern "C" {

    46 #endif

    48 /**

    49  * Generic loop statement for lists.

    50  *

    51  * The first argument is the type of the list and its elements (e.g. UcxList).

    52  * The structure invariant of the list must be as follows:

    53  * <ul>

    54  *   <li>a first (non-<code>NULL</code>) element</li>

    55  *   <li>for each element a reference to the <code>next</code> element (the

    56  *       variable name of the pointer MUST be <code>next</code>)</li>

    57  *   <li>the last element of the list MUST have the <code>next</code> pointer

    58  *       set to <code>NULL</code></li>

    59  * </ul>

    60  *

    61  * The second argument is a pointer to the list. In most cases this will be the

    62  * pointer to the first element of the list, but it may also be an arbitrary

    63  * element of the list. The iteration will then start with that element.

    64  *

    65  * The third argument is the name of the iteration variable. The scope of

    66  * this variable is limited to the <code>UCX_FOREACH</code> statement.

    67  *

    68  * @param type The type of <b>both</b> the list and the element

    69  * @param list The first element of the list

    70  * @param elem The variable name of the element

    71  */

    72 #define UCX_FOREACH(type,list,elem) \

    73         for (type elem = list ; elem != NULL ; elem = elem->next)

    75 /**

    76  * Function pointer to a compare function.

    77  *

    78  * The compare function shall take three arguments: the two values that shall be

    79  * compared and optional additional data.

    80  * The function shall then return -1 if the first argument is less than the

    81  * second argument, 1 if the first argument is greater than the second argument

    82  * and 0 if both arguments are equal. If the third argument is

    83  * <code>NULL</code>, it shall be ignored.

    84  */

    85 typedef int(*cmp_func)(void*,void*,void*);

    87 /**

    88  * Function pointer to a copy function.

    89  *

    90  * The copy function shall create a copy of the first argument and may use

    91  * additional data provided by the second argument. If the second argument is

    92  * <code>NULL</code>, it shall be ignored.

    94  * <b>Attention:</b> if pointers returned by functions of this type may be

    95  * passed to <code>free()</code> depends on the implementation of the

    96  * respective <code>copy_func</code>.

    97  */

    98 typedef void*(*copy_func)(void*,void*);

   100 /**

   101  * Function pointer to a write function.

   102  *

   103  * The signature of the write function shall be compatible to the signature

   104  * of standard <code>fwrite</code>, though it may use arbitrary data types for

   105  * source and destination.

   106  *

   107  * The arguments shall contain (in ascending order): a pointer to the source,

   108  * the length of one element, the element count, a pointer to the destination.

   109  */

   110 typedef size_t(*write_func)(const void*, size_t, size_t, void*);

   112 /**

   113  * Function pointer to a read function.

   114  *

   115  * The signature of the read function shall be compatible to the signature

   116  * of standard <code>fread</code>, though it may use arbitrary data types for

   117  * source and destination.

   118  *

   119  * The arguments shall contain (in ascending order): a pointer to the

   120  * destination, the length of one element, the element count, a pointer to the

   121  * source.

   122  */

   123 typedef size_t(*read_func)(void*, size_t, size_t, void*);

   125 #ifdef	__cplusplus

   126 }

   127 #endif

   129 #endif	/* UCX_H */

Mercurial > hg > ucx / file revision