omp_alloc.hpp

Go to the documentation of this file.

// $Id: omp_alloc.hpp 3804 2016-03-20 15:08:46Z bradbell $
# ifndef CPPAD_UTILITY_OMP_ALLOC_HPP
# define CPPAD_UTILITY_OMP_ALLOC_HPP

/* --------------------------------------------------------------------------
CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-16 Bradley M. Bell

CppAD is distributed under multiple licenses. This distribution is under
the terms of the
                    Eclipse Public License Version 1.0.

A copy of this license is included in the COPYING file of this distribution.
Please visit http://www.coin-or.org/CppAD/ for information on other licenses.
-------------------------------------------------------------------------- */
# include <cppad/utility/thread_alloc.hpp>
# ifdef _OPENMP
# include <omp.h>
# endif

namespace CppAD { // BEGIN_CPPAD_NAMESPACE
class omp_alloc{
// ============================================================================
public:
/*
$begin omp_max_num_threads$$
$spell
     cppad.hpp
     inv
     CppAD
     num
     omp_alloc
$$
$section Set and Get Maximum Number of Threads for omp_alloc Allocator$$

$head Deprecated 2011-08-31$$
Use the functions $cref/thread_alloc::parallel_setup/ta_parallel_setup/$$
and $cref/thread_alloc:num_threads/ta_num_threads/$$ instead.

$head Syntax$$
$codei%# include <cppad/utility/omp_alloc.hpp>
%$$
$codei%omp_alloc::set_max_num_threads(%number%)
%$$
$icode%number% = omp_alloc::get_max_num_threads()
%$$

$head Purpose$$
By default there is only one thread and all execution is in sequential mode
(not $cref/parallel/omp_in_parallel/$$).

$head number$$
The argument and return value $icode number$$ has prototype
$codei%
     size_t %number%
%$$
and must be greater than zero.

$head set_max_num_threads$$
Informs $cref omp_alloc$$ of the maximum number of OpenMP threads.

$head get_max_num_threads$$
Returns the valued used in the previous call to $code set_max_num_threads$$.
If there was no such previous call, the value one is returned
(and only thread number zero can use $cref omp_alloc$$).

$head Restrictions$$
The function $code set_max_num_threads$$ must be called before
the program enters $cref/parallel/omp_in_parallel/$$ execution mode.
In addition, this function cannot be called while in parallel mode.

$end
*/
     /*!
     Inform omp_alloc of the maximum number of OpenMP threads and enable
     parallel execution mode by initializing all statics in this file.

     \param number [in]
     maximum number of OpenMP threads.
     */
     static void set_max_num_threads(size_t number)
     {    thread_alloc::parallel_setup(
               number, omp_alloc::in_parallel, omp_alloc::get_thread_num
          );
          thread_alloc::hold_memory(number > 1);
     }
     /*!
     Get the current maximum number of OpenMP threads that omp_alloc can use.

     \return
     maximum number of OpenMP threads.
     */
     static size_t get_max_num_threads(void)
     {    return thread_alloc::num_threads(); }

/* -----------------------------------------------------------------------
$begin omp_in_parallel$$

$section Is The Current Execution in OpenMP Parallel Mode$$
$mindex in_parallel$$
$spell
     cppad.hpp
     omp_alloc
     bool
$$

$head Deprecated 2011-08-31$$
Use the function $cref/thread_alloc::in_parallel/ta_in_parallel/$$ instead.

$head Syntax$$
$codei%# include <cppad/utility/omp_alloc.hpp>
%$$
$icode%flag% = omp_alloc::in_parallel()%$$

$head Purpose$$
Some of the $cref omp_alloc$$ allocation routines have different
specifications for parallel (not sequential) execution mode.
This routine enables you to determine if the current execution mode
is sequential or parallel.

$head flag$$
The return value has prototype
$codei%
     bool %flag%
%$$
It is true if the current execution is in parallel mode
(possibly multi-threaded) and false otherwise (sequential mode).

$head Example$$
$cref omp_alloc.cpp$$

$end
*/
     /// Are we in a parallel execution state; i.e., is it possible that
     /// other threads are currently executing.
     static bool in_parallel(void)
     {
# ifdef _OPENMP
          return omp_in_parallel() != 0;
# else
          return false;
# endif
     }

/* -----------------------------------------------------------------------
$begin omp_get_thread_num$$
$spell
     cppad.hpp
     CppAD
     num
     omp_alloc
     cppad.hpp
$$

$section Get the Current OpenMP Thread Number$$
$mindex get_thread_num$$

$head Deprecated 2011-08-31$$
Use the function $cref/thread_alloc::thread_num/ta_thread_num/$$ instead.

$head Syntax$$
$codei%# include <cppad/utility/omp_alloc.hpp>
%$$
$icode%thread% = omp_alloc::get_thread_num()%$$

$head Purpose$$
Some of the $cref omp_alloc$$ allocation routines have a thread number.
This routine enables you to determine the current thread.

$head thread$$
The return value $icode thread$$ has prototype
$codei%
     size_t %thread%
%$$
and is the currently executing thread number.
If $code _OPENMP$$ is not defined, $icode thread$$ is zero.

$head Example$$
$cref omp_alloc.cpp$$

$end
*/
     /// Get current OpenMP thread number (zero if _OpenMP not defined).
     static size_t get_thread_num(void)
     {
# ifdef _OPENMP
          size_t thread = static_cast<size_t>( omp_get_thread_num() );
          return thread;
# else
          return 0;
# endif
     }
/* -----------------------------------------------------------------------
$begin omp_get_memory$$
$spell
     cppad.hpp
     num
     ptr
     omp_alloc
$$

$section Get At Least A Specified Amount of Memory$$

$head Deprecated 2011-08-31$$
Use the function $cref/thread_alloc::get_memory/ta_get_memory/$$ instead.

$head Syntax$$
$codei%# include <cppad/utility/omp_alloc.hpp>
%$$
$icode%v_ptr% = omp_alloc::get_memory(%min_bytes%, %cap_bytes%)%$$

$head Purpose$$
Use $cref omp_alloc$$ to obtain a minimum number of bytes of memory
(for use by the $cref/current thread/omp_get_thread_num/$$).

$head min_bytes$$
This argument has prototype
$codei%
     size_t %min_bytes%
%$$
It specifies the minimum number of bytes to allocate.

$head cap_bytes$$
This argument has prototype
$codei%
     size_t& %cap_bytes%
%$$
It's input value does not matter.
Upon return, it is the actual number of bytes (capacity)
that have been allocated for use,
$codei%
     %min_bytes% <= %cap_bytes%
%$$

$head v_ptr$$
The return value $icode v_ptr$$ has prototype
$codei%
     void* %v_ptr%
%$$
It is the location where the $icode cap_bytes$$ of memory
that have been allocated for use begins.

$head Allocation Speed$$
This allocation should be faster if the following conditions hold:
$list number$$
The memory allocated by a previous call to $code get_memory$$
is currently available for use.
$lnext
The current $icode min_bytes$$ is between
the previous $icode min_bytes$$ and previous $icode cap_bytes$$.
$lend

$head Example$$
$cref omp_alloc.cpp$$

$end
*/
     /*!
     Use omp_alloc to get a specified amount of memory.

     If the memory allocated by a previous call to \c get_memory is now
     avaialable, and \c min_bytes is between its previous value
     and the previous \c cap_bytes, this memory allocation will have
     optimal speed. Otherwise, the memory allocation is more complicated and
     may have to wait for other threads to complete an allocation.

     \param min_bytes [in]
     The minimum number of bytes of memory to be obtained for use.

     \param cap_bytes [out]
     The actual number of bytes of memory obtained for use.

     \return
     pointer to the beginning of the memory allocted for use.
     */
     static void* get_memory(size_t min_bytes, size_t& cap_bytes)
     {    return thread_alloc::get_memory(min_bytes, cap_bytes); }

/* -----------------------------------------------------------------------
$begin omp_return_memory$$
$spell
     cppad.hpp
     ptr
     omp_alloc
$$

$section Return Memory to omp_alloc$$
$mindex return_memory$$

$head Deprecated 2011-08-31$$
Use the function $cref/thread_alloc::return_memory/ta_return_memory/$$ instead.

$head Syntax$$
$codei%# include <cppad/utility/omp_alloc.hpp>
%$$
$codei%omp_alloc::return_memory(%v_ptr%)%$$

$head Purpose$$
If $cref omp_max_num_threads$$ is one,
the memory is returned to the system.
Otherwise, the memory is retained by $cref omp_alloc$$ for quick future use
by the thread that allocated to memory.

$head v_ptr$$
This argument has prototype
$codei%
     void* %v_ptr%
%$$.
It must be a pointer to memory that is currently in use; i.e.
obtained by a previous call to $cref omp_get_memory$$ and not yet returned.

$head Thread$$
Either the $cref/current thread/omp_get_thread_num/$$ must be the same as during
the corresponding call to $cref omp_get_memory$$,
or the current execution mode must be sequential
(not $cref/parallel/omp_in_parallel/$$).

$head NDEBUG$$
If $code NDEBUG$$ is defined, $icode v_ptr$$ is not checked (this is faster).
Otherwise, a list of in use pointers is searched to make sure
that $icode v_ptr$$ is in the list.

$head Example$$
$cref omp_alloc.cpp$$

$end
*/
     /*!
     Return memory that was obtained by \c get_memory.
     If  <code>max_num_threads(0) == 1</code>,
     the memory is returned to the system.
     Otherwise, it is retained by \c omp_alloc and available for use by
     \c get_memory for this thread.

     \param v_ptr [in]
     Value of the pointer returned by \c get_memory and still in use.
     After this call, this pointer will available (and not in use).

     \par
     We must either be in sequential (not parallel) execution mode,
     or the current thread must be the same as for the corresponding call
     to \c get_memory.
     */
     static void return_memory(void* v_ptr)
     {    thread_alloc::return_memory(v_ptr); }
/* -----------------------------------------------------------------------
$begin omp_free_available$$
$spell
     cppad.hpp
     omp_alloc
$$

$section Free Memory Currently Available for Quick Use by a Thread$$
$mindex free_available$$

$head Deprecated 2011-08-31$$
Use the function $cref/thread_alloc::free_available/ta_free_available/$$
instead.

$head Syntax$$
$codei%# include <cppad/utility/omp_alloc.hpp>
%$$
$codei%omp_alloc::free_available(%thread%)%$$

$head Purpose$$
Free memory, currently available for quick use by a specific thread,
for general future use.

$head thread$$
This argument has prototype
$codei%
     size_t %thread%
%$$
Either $cref omp_get_thread_num$$ must be the same as $icode thread$$,
or the current execution mode must be sequential
(not $cref/parallel/omp_in_parallel/$$).

$head Example$$
$cref omp_alloc.cpp$$

$end
*/
     /*!
     Return all the memory being held as available for a thread to the system.

     \param thread [in]
     this thread that will no longer have any available memory after this call.
     This must either be the thread currently executing, or we must be
     in sequential (not parallel) execution mode.
     */
     static void free_available(size_t thread)
     {    thread_alloc::free_available(thread); }
/* -----------------------------------------------------------------------
$begin omp_inuse$$
$spell
     cppad.hpp
     num
     inuse
     omp_alloc
$$

$section Amount of Memory a Thread is Currently Using$$
$mindex inuse$$

$head Deprecated 2011-08-31$$

$head Syntax$$
$codei%# include <cppad/utility/omp_alloc.hpp>
%$$
$icode%num_bytes% = omp_alloc::inuse(%thread%)%$$
Use the function $cref/thread_alloc::inuse/ta_inuse/$$ instead.

$head Purpose$$
Memory being managed by $cref omp_alloc$$ has two states,
currently in use by the specified thread,
and quickly available for future use by the specified thread.
This function informs the program how much memory is in use.

$head thread$$
This argument has prototype
$codei%
     size_t %thread%
%$$
Either $cref omp_get_thread_num$$ must be the same as $icode thread$$,
or the current execution mode must be sequential
(not $cref/parallel/omp_in_parallel/$$).

$head num_bytes$$
The return value has prototype
$codei%
     size_t %num_bytes%
%$$
It is the number of bytes currently in use by the specified thread.

$head Example$$
$cref omp_alloc.cpp$$

$end
*/
     /*!
     Determine the amount of memory that is currently inuse.

     \param thread [in]
     Thread for which we are determining the amount of memory
     (must be < CPPAD_MAX_NUM_THREADS).
     Durring parallel execution, this must be the thread
     that is currently executing.

     \return
     The amount of memory in bytes.
     */
     static size_t inuse(size_t thread)
     {    return thread_alloc::inuse(thread); }
/* -----------------------------------------------------------------------
$begin omp_available$$
$spell
     cppad.hpp
     num
     omp_alloc
$$

$section Amount of Memory Available for Quick Use by a Thread$$

$head Deprecated 2011-08-31$$
Use the function $cref/thread_alloc::available/ta_available/$$ instead.

$head Syntax$$
$codei%# include <cppad/utility/omp_alloc.hpp>
%$$
$icode%num_bytes% = omp_alloc::available(%thread%)%$$

$head Purpose$$
Memory being managed by $cref omp_alloc$$ has two states,
currently in use by the specified thread,
and quickly available for future use by the specified thread.
This function informs the program how much memory is available.

$head thread$$
This argument has prototype
$codei%
     size_t %thread%
%$$
Either $cref omp_get_thread_num$$ must be the same as $icode thread$$,
or the current execution mode must be sequential
(not $cref/parallel/omp_in_parallel/$$).

$head num_bytes$$
The return value has prototype
$codei%
     size_t %num_bytes%
%$$
It is the number of bytes currently available for use by the specified thread.

$head Example$$
$cref omp_alloc.cpp$$

$end
*/
     /*!
     Determine the amount of memory that is currently available for use.

     \copydetails inuse
     */
     static size_t available(size_t thread)
     {    return thread_alloc::available(thread); }
/* -----------------------------------------------------------------------
$begin omp_create_array$$
$spell
     cppad.hpp
     omp_alloc
     sizeof
$$

$section Allocate Memory and Create A Raw Array$$
$mindex create_array$$

$head Deprecated 2011-08-31$$
Use the function $cref/thread_alloc::create_array/ta_create_array/$$ instead.

$head Syntax$$
$codei%# include <cppad/utility/omp_alloc.hpp>
%$$
$icode%array% = omp_alloc::create_array<%Type%>(%size_min%, %size_out%)%$$.

$head Purpose$$
Create a new raw array using $cref omp_alloc$$ a fast memory allocator
that works well in a multi-threading OpenMP environment.

$head Type$$
The type of the elements of the array.

$head size_min$$
This argument has prototype
$codei%
     size_t %size_min%
%$$
This is the minimum number of elements that there can be
in the resulting $icode array$$.

$head size_out$$
This argument has prototype
$codei%
     size_t& %size_out%
%$$
The input value of this argument does not matter.
Upon return, it is the actual number of elements
in $icode array$$
($icode% size_min %<=% size_out%$$).

$head array$$
The return value $icode array$$ has prototype
$codei%
     %Type%* %array%
%$$
It is array with $icode size_out$$ elements.
The default constructor for $icode Type$$ is used to initialize the
elements of $icode array$$.
Note that $cref omp_delete_array$$
should be used to destroy the array when it is no longer needed.

$head Delta$$
The amount of memory $cref omp_inuse$$ by the current thread,
will increase $icode delta$$ where
$codei%
     sizeof(%Type%) * (%size_out% + 1) > %delta% >= sizeof(%Type%) * %size_out%
%$$
The $cref omp_available$$ memory will decrease by $icode delta$$,
(and the allocation will be faster)
if a previous allocation with $icode size_min$$ between its current value
and $icode size_out$$ is available.

$head Example$$
$cref omp_alloc.cpp$$

$end
*/
     /*!
     Use omp_alloc to Create a Raw Array.

     \tparam Type
     The type of the elements of the array.

     \param size_min [in]
     The minimum number of elements in the array.

     \param size_out [out]
     The actual number of elements in the array.

     \return
     pointer to the first element of the array.
     The default constructor is used to initialize
     all the elements of the array.

     \par
     The \c extra_ field, in the \c omp_alloc node before the return value,
     is set to size_out.
     */
     template <class Type>
     static Type* create_array(size_t size_min, size_t& size_out)
     {    return thread_alloc::create_array<Type>(size_min, size_out); }
/* -----------------------------------------------------------------------
$begin omp_delete_array$$
$spell
     cppad.hpp
     omp_alloc
     sizeof
$$

$section Return A Raw Array to The Available Memory for a Thread$$
$mindex delete_array$$

$head Deprecated 2011-08-31$$
Use the function $cref/thread_alloc::delete_array/ta_delete_array/$$ instead.

$head Syntax$$
$codei%# include <cppad/utility/omp_alloc.hpp>
%$$
$codei%omp_alloc::delete_array(%array%)%$$.

$head Purpose$$
Returns memory corresponding to a raw array
(create by $cref omp_create_array$$) to the
$cref omp_available$$ memory pool for the current thread.

$head Type$$
The type of the elements of the array.

$head array$$
The argument $icode array$$ has prototype
$codei%
     %Type%* %array%
%$$
It is a value returned by $cref omp_create_array$$ and not yet deleted.
The $icode Type$$ destructor is called for each element in the array.

$head Thread$$
The $cref/current thread/omp_get_thread_num/$$ must be the
same as when $cref omp_create_array$$ returned the value $icode array$$.
There is an exception to this rule:
when the current execution mode is sequential
(not $cref/parallel/omp_in_parallel/$$) the current thread number does not matter.

$head Delta$$
The amount of memory $cref omp_inuse$$ will decrease by $icode delta$$,
and the $cref omp_available$$ memory will increase by $icode delta$$,
where $cref/delta/omp_create_array/Delta/$$
is the same as for the corresponding call to $code create_array$$.

$head Example$$
$cref omp_alloc.cpp$$

$end
*/
     /*!
     Return Memory Used for a Raw Array to the Available Pool.

     \tparam Type
     The type of the elements of the array.

     \param array [in]
     A value returned by \c create_array that has not yet been deleted.
     The \c Type destructor is used to destroy each of the elements
     of the array.

     \par
     Durring parallel execution, the current thread must be the same
     as during the corresponding call to \c create_array.
     */
     template <class Type>
     static void delete_array(Type* array)
     {    thread_alloc::delete_array(array); }
};
/* --------------------------------------------------------------------------
$begin omp_efficient$$
$spell
     cppad.hpp
     omp_alloc
     ptr
     num
     bool
     const
$$

$section Check If A Memory Allocation is Efficient for Another Use$$

$head Removed$$
This function has been removed because speed tests seem to indicate
it is just as fast, or faster, to free and then reallocate the memory.

$head Syntax$$
$codei%# include <cppad/utility/omp_alloc.hpp>
%$$
$icode%flag% = omp_alloc::efficient(%v_ptr%, %num_bytes%)%$$

$head Purpose$$
Check if memory that is currently in use is an efficient
allocation for a specified number of bytes.

$head v_ptr$$
This argument has prototype
$codei%
     const void* %v_ptr%
%$$.
It must be a pointer to memory that is currently in use; i.e.
obtained by a previous call to $cref omp_get_memory$$ and not yet returned.

$head num_bytes$$
This argument has prototype
$codei%
     size_t %num_bytes%
%$$
It specifies the number of bytes of the memory allocated by $icode v_ptr$$
that we want to use.

$head flag$$
The return value has prototype
$codei%
     bool %flag%
%$$
It is true,
a call to $code get_memory$$ with
$cref/min_bytes/omp_get_memory/min_bytes/$$
equal to $icode num_bytes$$ would result in a value for
$cref/cap_bytes/omp_get_memory/cap_bytes/$$ that is the same as when $code v_ptr$$
was returned by $code get_memory$$; i.e.,
$icode v_ptr$$ is an efficient memory block for $icode num_bytes$$
bytes of information.

$head Thread$$
Either the $cref/current thread/omp_get_thread_num/$$ must be the same as during
the corresponding call to $cref omp_get_memory$$,
or the current execution mode must be sequential
(not $cref/parallel/omp_in_parallel/$$).

$head NDEBUG$$
If $code NDEBUG$$ is defined, $icode v_ptr$$ is not checked (this is faster).
Otherwise, a list of in use pointers is searched to make sure
that $icode v_ptr$$ is in the list.

$end
---------------------------------------------------------------------------
$begin old_max_num_threads$$
$spell
     cppad.hpp
     inv
     CppAD
     num
     omp_alloc
$$
$section Set Maximum Number of Threads for omp_alloc Allocator$$
$mindex max_num_threads$$

$head Removed$$
This function has been removed from the CppAD API.
Use the function $cref/thread_alloc::parallel_setup/ta_parallel_setup/$$
in its place.

$head Syntax$$
$codei%# include <cppad/utility/omp_alloc.hpp>
%$$
$codei%omp_alloc::max_num_threads(%number%)%$$

$head Purpose$$
By default there is only one thread and all execution is in sequential mode
(not $cref/parallel/omp_in_parallel/$$).

$head number$$
The argument $icode number$$ has prototype
$codei%
     size_t %number%
%$$
It must be greater than zero and specifies the maximum number of
OpenMP threads that will be active at one time.

$head Restrictions$$
This function must be called before the program enters
$cref/parallel/omp_in_parallel/$$ execution mode.

$end
-------------------------------------------------------------------------------
*/
} // END_CPPAD_NAMESPACE

# endif