lovr-ODE/include/ode/cooperative.h

/*************************************************************************
 *                                                                       *
 * Open Dynamics Engine, Copyright (C) 2001-2003 Russell L. Smith.       *
 * All rights reserved.  Email: [email protected]   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_