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