------------------------------------------
lines 5-73 of file: xrst/multi_thread.xrst
------------------------------------------

{xrst_begin multi_thread}

Using CppAD in a Multi-Threading Environment
############################################

Purpose
*******
Extra steps and care must be taken to use CppAD
in :ref:`parallel<ta_in_parallel-name>` execution mode.
This section collects this information in one place.

CPPAD_MAX_NUM_THREADS
*********************
The value ``CPPAD_MAX_NUM_THREADS`` is an absolute maximum for
the number of threads that CppAD should support.
If this preprocessor symbol is defined
before including any CppAD header files,
it must be an integer greater than or equal to one.
Otherwise, :ref:`cmake@cppad_max_num_threads`
is used to define this preprocessor symbol.
Note that the minimum allowable value for
*cppad_max_num_threads* is 4; i.e., you can only
get smaller values for ``CPPAD_MAX_NUM_THREADS`` by
defining it before including the CppAD header files.

parallel_setup
**************
Using any of the following routines in a multi-threading environment
requires that :ref:`thread_alloc::parallel_setup<ta_parallel_setup-name>`
has been completed:
:ref:`CppAD::vector<CppAD_vector@Memory and Parallel Mode>` ,
:ref:`CheckSimpleVector<CheckSimpleVector@Parallel Mode>` ,
:ref:`CheckNumericType<CheckNumericType@Parallel Mode>` ,
:ref:`parallel_ad-name` .

hold_memory
***********
Memory allocation should be much faster after calling
``hold_memory`` with
:ref:`ta_hold_memory@value` equal to true.
This may even be true if there is only one thread.

Parallel AD
***********
One must first call
:ref:`thread_alloc::parallel_setup<ta_parallel_setup-name>`
and then call :ref:`parallel_ad-name` before using ``AD`` types
in :ref:`parallel<ta_in_parallel-name>` execution mode.
In addition, see :ref:`parallel_ad@Other Initialization` .

Same Thread
***********
Some operations must be preformed by the same thread:
:ref:`ADFun<fun_construct@Parallel Mode>` ,
:ref:`Independent-name` , :ref:`Dependent-name` .

Parallel Prohibited
*******************
The following routine cannot be called in parallel mode:
:ref:`ErrorHandler constructor<ErrorHandler@Constructor@Parallel Mode>` .

Contents
********
{xrst_toc_table
   include/cppad/core/parallel_ad.hpp
   example/multi_thread/thread_test.cpp
}

{xrst_end multi_thread}