Cosmetic: Commentary spelling corrections by Max Seidenstücker
[ode.git] / include / ode / cooperative.h
blob59757dc95114bc4719ade48e1d4b7931e2ba7f30
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 *************************************************************************/
23 #ifndef _ODE_COOPERATIVE_H_
24 #define _ODE_COOPERATIVE_H_
27 #include <ode/common.h>
28 #include <ode/threading.h>
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
35 /**
36 * @defgroup coop Cooperative Algorithms
38 * Algorithms implemented as multiple threads doing work cooperatively.
42 struct dxCooperative;
43 struct dxResourceRequirements;
44 struct dxResourceContainer;
46 /**
47 * @brief A container for cooperative algorithms shared context
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).
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.
57 typedef struct dxCooperative *dCooperativeID;
60 /**
61 * @brief A container for resource requirements information
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.
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.
73 * @ingroup coop
74 * @see dCooperativeID
75 * @see dResourceContainerID
77 typedef struct dxResourceRequirements *dResourceRequirementsID;
79 /**
80 * @brief A container for algorithm allocated resources
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.
86 * @ingroup coop
87 * @see dResourceRequirementsID
88 * @see dCooperativeID
90 typedef struct dxResourceContainer *dResourceContainerID;
93 /**
94 * @brief Creates a Cooperative object related to the specified threading.
96 * NULL's are allowed for the threading. In this case the default (global) self-threading
97 * object will be used.
99 * Use @c dCooperativeDestroy to destroy the object. The Cooperative object must exist
100 * until after all the objects referencing it are destroyed.
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
108 ODE_API dCooperativeID dCooperativeCreate(const dThreadingFunctionsInfo *functionInfo/*=NULL*/, dThreadingImplementationID threadingImpl/*=NULL*/);
111 * @brief Destroys Cooperative object.
113 * The Cooperative object can only be destroyed after all the objects referencing it.
115 * @param cooperative A Cooperative object to be deleted (NULL is allowed)
116 * @ingroup coop
117 * @see dCooperativeCreate
119 ODE_API void dCooperativeDestroy(dCooperativeID cooperative);
123 * @brief Creates a ResourceRequirements object related to a Cooperative.
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.
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.
133 * Use @c dResourceRequirementsDestroy to delete the object when it is no longer needed.
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
144 ODE_API dResourceRequirementsID dResourceRequirementsCreate(dCooperativeID cooperative);
147 * @brief Destroys ResourceRequirements object.
149 * The ResourceRequirements object can be destroyed at any time with no regards
150 * to other objects' lifetime.
152 * @param requirements A ResourceRequirements object to be deleted (NULL is allowed)
153 * @ingroup coop
154 * @see dResourceRequirementsCreate
156 ODE_API void dResourceRequirementsDestroy(dResourceRequirementsID requirements);
159 * @brief Clones ResourceRequirements object.
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.
165 * The object created with the function must later be destroyed with @c dResourceRequirementsDestroy.
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
174 ODE_API dResourceRequirementsID dResourceRequirementsClone(/*const */dResourceRequirementsID requirements);
177 * @brief Merges one ResourceRequirements object into another ResourceRequirements object.
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. Both objects should normally have been created
182 * with the same Cooperative object.
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
191 ODE_API void dResourceRequirementsMergeIn(dResourceRequirementsID summaryRequirements, /*const */dResourceRequirementsID extraRequirements);
195 * @brief Allocates resources as specified in ResourceRequirements object.
197 * The ResourceContainer object can be used in cooperative computation algorithms.
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.
203 * Use @c dResourceContainerDestroy to delete the object and release the resources
204 * when they are no longer needed.
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
212 ODE_API dResourceContainerID dResourceContainerAcquire(/*const */dResourceRequirementsID requirements);
215 * @brief Destroys ResourceContainer object and releases resources allocated in it.
217 * @param resources A ResourceContainer object to be deleted (NULL is allowed)
218 * @ingroup coop
219 * @see dResourceContainerAcquire
221 ODE_API void dResourceContainerDestroy(dResourceContainerID resources);
224 #ifdef __cplusplus
225 } // extern "C"
226 #endif
229 #endif // #ifndef _ODE_COOPERATIVE_H_