misc/builddeps/linux64/ode/include/ode/cooperative.h

   1 /*************************************************************************
   2  *                                                                       *
   3  * Open Dynamics Engine, Copyright (C) 2001-2003 Russell L. Smith.       *
   4  * All rights reserved.  Email: russ@q12.org   Web: www.q12.org          *
   5  *                                                                       *
   6  * This library is free software; you can redistribute it and/or         *
   7  * modify it under the terms of EITHER:                                  *
   8  *   (1) The GNU Lesser General Public License as published by the Free  *
   9  *       Software Foundation; either version 2.1 of the License, or (at  *
  10  *       your option) any later version. The text of the GNU Lesser      *
  11  *       General Public License is included with this library in the     *
  12  *       file LICENSE.TXT.                                               *
  13  *   (2) The BSD-style license that is included with this library in     *
  14  *       the file LICENSE-BSD.TXT.                                       *
  15  *                                                                       *
  16  * This library is distributed in the hope that it will be useful,       *
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the files    *
  19  * LICENSE.TXT and LICENSE-BSD.TXT for more details.                     *
  20  *                                                                       *
  21  *************************************************************************/
  22
  23 #ifndef _ODE_COOPERATIVE_H_
  24 #define _ODE_COOPERATIVE_H_
  25
  26
  27 #include <ode/common.h>
  28 #include <ode/threading.h>
  29
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /**
  36  * @defgroup coop Cooperative Algorithms
  37  *
  38  * Algorithms implemented as multiple threads doing work cooperatively.
  39  */
  40
  41
  42 struct dxCooperative;
  43 struct dxResourceRequirements;
  44 struct dxResourceContainer;
  45
  46 /**
  47  * @brief A container for cooperative algorithms shared context
  48  *
  49  * The Cooperative is a container for cooperative algorithms shared context.
  50  * At present it contains threading object (either a real one or a defaulted
  51  * self-threading).
  52  *
  53  * Cooperative use in functions performing computations must be serialized. That is,
  54  * functions referring to a single instance of Cooperative object must not be called in
  55  * parallel.
  56  */
  57 typedef struct dxCooperative *dCooperativeID;
  58
  59
  60 /**
  61  * @brief A container for resource requirements information
  62  *
  63  * The ResourceRequirements object is a container for descriptive information
  64  * regarding what resources (memory, synchronization objects, etc.) need to be
  65  * allocated for particular computations. The object can be used for accumulating
  66  * resource requirement maxima over multiple functions and then allocating resources
  67  * that would suffice for any of those function calls.
  68  *
  69  * ResourceRequirements objects maintain relations to Cooperative objects since
  70  * amounts of resources that could be required can depend on characteristics of
  71  * shared context, e.g. on maximal number of threads in the threading object.
  72  *
  73  * @ingroup coop
  74  * @see dCooperativeID
  75  * @see dResourceContainerID
  76  */
  77 typedef struct dxResourceRequirements *dResourceRequirementsID;
  78
  79 /**
  80  * @brief A container for algorithm allocated resources
  81  *
  82  * The ResourceContainer object can contain resources allocated according to information
  83  * in a ResourceRequirements. The resources inherit link to the threading object
  84  * from the requirements they are allocated according to.
  85  *
  86  * @ingroup coop
  87  * @see dResourceRequirementsID
  88  * @see dCooperativeID
  89  */
  90 typedef struct dxResourceContainer *dResourceContainerID;
  91
  92
  93  /**
  94  * @brief Creates a Cooperative object related to the specified threading.
  95  *
  96  * NULL's are allowed for the threading. In this case the default (global) self-threading
  97  * object will be used.
  98  *
  99  * Use @c dCooperativeDestroy to destroy the object. The Cooperative object must exist
 100  * until after all the objects referencing it are destroyed.
 101  *
 102  * @param functionInfo The threading functions to use
 103  * @param threadingImpl The threading implementation object to use
 104  * @returns The Cooperative object instance or NULL if allocation fails.
 105  * @ingroup coop
 106  * @see dCooperativeDestroy
 107  */
 108 ODE_API dCooperativeID dCooperativeCreate(const dThreadingFunctionsInfo *functionInfo/*=NULL*/, dThreadingImplementationID threadingImpl/*=NULL*/);
 109
 110  /**
 111  * @brief Destroys Cooperative object.
 112  *
 113  * The Cooperative object can only be destroyed after all the objects referencing it.
 114  *
 115  * @param cooperative A Cooperative object to be deleted (NULL is allowed)
 116  * @ingroup coop
 117  * @see dCooperativeCreate
 118  */
 119 ODE_API void dCooperativeDestroy(dCooperativeID cooperative);
 120
 121
 122  /**
 123  * @brief Creates a ResourceRequirements object related to a Cooperative.
 124  *
 125  * The object is purely descriptive and does not contain any resources by itself.
 126  * The actual resources are allocated by means of ResourceContainer object.
 127  *
 128  * The object is created with empty requirements. It can be then used to accumulate
 129  * requirements for one or more function calls and can be cloned or merged with others.
 130  * The actual requirements information is added to the object by computation related
 131  * functions.
 132  *
 133  * Use @c dResourceRequirementsDestroy to delete the object when it is no longer needed.
 134  *
 135  * @param cooperative A Cooperative object to be used
 136  * @returns The ResourceRequirements object instance or NULL if allocation fails
 137  * @ingroup coop
 138  * @see dResourceRequirementsDestroy
 139  * @see dResourceRequirementsClone
 140  * @see dResourceRequirementsMergeIn
 141  * @see dCooperativeCreate
 142  * @see dResourceContainerAcquire
 143  */
 144 ODE_API dResourceRequirementsID dResourceRequirementsCreate(dCooperativeID cooperative);
 145
 146  /**
 147  * @brief Destroys ResourceRequirements object.
 148  *
 149  * The ResourceRequirements object can be destroyed at any time with no regards
 150  * to other objects' lifetime.
 151  *
 152  * @param requirements A ResourceRequirements object to be deleted (NULL is allowed)
 153  * @ingroup coop
 154  * @see dResourceRequirementsCreate
 155  */
 156 ODE_API void dResourceRequirementsDestroy(dResourceRequirementsID requirements);
 157
 158  /**
 159  * @brief Clones ResourceRequirements object.
 160  *
 161  * The function creates a copy of the ResourceRequirements object with all the
 162  * contents and the relation to Cooperative matching. The object passed in
 163  * the parameter is not changed.
 164  *
 165  * The object created with the function must later be destroyed with @c dResourceRequirementsDestroy.
 166  *
 167  * @param requirements A ResourceRequirements object to be cloned
 168  * @returns A handle to the new object or NULL if allocation fails
 169  * @ingroup coop
 170  * @see dResourceRequirementsCreate
 171  * @see dResourceRequirementsDestroy
 172  * @see dResourceRequirementsMergeIn
 173  */
 174 ODE_API dResourceRequirementsID dResourceRequirementsClone(/*const */dResourceRequirementsID requirements);
 175
 176  /**
 177  * @brief Merges one ResourceRequirements object into another ResourceRequirements object.
 178  *
 179  * The function updates @a summaryRequirements requirements to be also sufficient
 180  * for the purposes @a extraRequirements could be used for. The @a extraRequirements
 181  * object is not changed. The both objects should normally have had been created
 182  * with the same Cooperative object.
 183  *
 184  * @param summaryRequirements A ResourceRequirements object to be changed
 185  * @param extraRequirements A ResourceRequirements the requirements to be taken from
 186  * @ingroup coop
 187  * @see dResourceRequirementsCreate
 188  * @see dResourceRequirementsDestroy
 189  * @see dResourceRequirementsClone
 190  */
 191 ODE_API void dResourceRequirementsMergeIn(dResourceRequirementsID summaryRequirements, /*const */dResourceRequirementsID extraRequirements);
 192
 193
 194  /**
 195  * @brief Allocates resources as specified in ResourceRequirements object.
 196  *
 197  * The ResourceContainer object can be used in cooperative computation algorithms.
 198  *
 199  * The same @a requirements object can be passed to many resource allocations
 200  * (with or without modifications) and can be deleted immediately, without waiting
 201  * for the ResourceContainer object destruction.
 202  *
 203  * Use @c dResourceContainerDestroy to delete the object and release the resources
 204  * when they are no longer needed.
 205  *
 206  * @param requirements The ResourceRequirements object to allocate resources according to
 207  * @returns A ResourceContainer object instance with the resources allocated or NULL if allocation fails
 208  * @ingroup coop
 209  * @see dResourceContainerDestroy
 210  * @see dResourceRequirementsCreate
 211  */
 212 ODE_API dResourceContainerID dResourceContainerAcquire(/*const */dResourceRequirementsID requirements);
 213
 214  /**
 215  * @brief Destroys ResourceContainer object and releases resources allocated in it.
 216  *
 217  * @param resources A ResourceContainer object to be deleted (NULL is allowed)
 218  * @ingroup coop
 219  * @see dResourceContainerAcquire
 220  */
 221 ODE_API void dResourceContainerDestroy(dResourceContainerID resources);
 222
 223
 224 #ifdef __cplusplus
 225 } // extern "C"
 226 #endif
 227
 228
 229 #endif // #ifndef _ODE_COOPERATIVE_H_