
<refentry id="OfxMultiThreadSuiteV1">
  <refmeta>
    <refentrytitle><type>OfxMultiThreadSuiteV1</type></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxMultiThreadSuiteV1</function></refname>
    <refpurpose>OFX suite that provides simple SMP style multi-processing</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
     <blockquote><programlisting>
#include "ofxMultiThread.h"
typedef struct OfxMultiThreadSuiteV1 {
  OfxStatus (*multiThread)(OfxThreadFunctionV1 func,
			   unsigned int nThreads,
			   void *customArg);
  OfxStatus (*multiThreadNumCPUs)(unsigned int *nCPUs);
  OfxStatus (*multiThreadIndex)(unsigned int *threadIndex);
  int (*multiThreadIsSpawnedThread)(void);
  OfxStatus (*mutexCreate)(OfxMutexHandle *mutex, int lockCount);
  OfxStatus (*mutexDestroy)(const OfxMutexHandle mutex);
  OfxStatus (*mutexLock)(const OfxMutexHandle mutex);
  OfxStatus (*mutexUnLock)(const OfxMutexHandle mutex);
  OfxStatus (*mutexTryLock)(const OfxMutexHandle mutex);
 } OfxMultiThreadSuiteV1;

</programlisting></blockquote>
     </refsynopsisdiv>
    <refsect1>
      <title>Description</title>    </refsect1>
</refentry>

<refentry id="OfxMultiThreadSuiteV1_multiThread">
  <refmeta>
    <refentrytitle><function>OfxMultiThreadSuiteV1::multiThread</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxMultiThreadSuiteV1::multiThread</function></refname>
       <refpurpose>Function to spawn SMP threads</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxMultiThread.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*multiThread)</function></funcdef>
              <paramdef>OfxThreadFunctionV1<parameter>func</parameter></paramdef>
              <paramdef>unsigned int<parameter>nThreads</parameter></paramdef>
              <paramdef>void *<parameter>customArg</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>func - The function to call in each thread.
</listitem>
<listitem>nThreads - The number of threads to launch
</listitem>
<listitem>customArg - The paramter to pass to customArg of func in each thread.
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
This function will spawn nThreads separate threads of computation (typically one per CPU) 
to allow something to perform symmetric multi processing. Each thread will call 'func' passing
in the index of the thread and the number of threads actually launched.
</para>
<para>
multiThread will not return until all the spawned threads have returned. It is up to the host
how it waits for all the threads to return (busy wait, blocking, whatever).
</para>
<para>
<emphasis> nThreads</emphasis> can be more than the value returned by multiThreadNumCPUs, however the threads will
be limitted to the number of CPUs returned by multiThreadNumCPUs.
</para>
<para>
This function cannot be called recursively.
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the function func has executed and returned sucessfully</listitem>
  <listitem><link linkend="kOfxStatFailed"><code>kOfxStatFailed</code></link>, the threading function failed to launch</listitem>
  <listitem><link linkend="kOfxStatErrExists"><code>kOfxStatErrExists</code></link>, failed in an attempt to call multiThread recursively,</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxMultiThreadSuiteV1_multiThreadNumCPUs">
  <refmeta>
    <refentrytitle><function>OfxMultiThreadSuiteV1::multiThreadNumCPUs</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxMultiThreadSuiteV1::multiThreadNumCPUs</function></refname>
       <refpurpose>Function which indicates the number of CPUs available for SMP processing</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxMultiThread.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*multiThreadNumCPUs)</function></funcdef>
              <paramdef>unsigned int *<parameter>nCPUs</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>nCPUs - pointer to an integer where the result is returned
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
This value may be less than the actual number of CPUs on a machine, as the host may reserve other CPUs for itself.
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, all was OK and the maximum number of threads is in nThreads.</listitem>
  <listitem><link linkend="kOfxStatFailed"><code>kOfxStatFailed</code></link>, the function failed to get the number of CPUs </listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxMultiThreadSuiteV1_multiThreadIndex">
  <refmeta>
    <refentrytitle><function>OfxMultiThreadSuiteV1::multiThreadIndex</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxMultiThreadSuiteV1::multiThreadIndex</function></refname>
       <refpurpose>Function which indicates the index of the current thread</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxMultiThread.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*multiThreadIndex)</function></funcdef>
              <paramdef>unsigned int *<parameter>threadIndex</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>threadIndex - pointer to an integer where the result is returned
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
This function returns the thread index, which is the same as the <emphasis> threadIndex</emphasis> argument passed to the <link linkend="OfxThreadFunctionV1"><code>OfxThreadFunctionV1</code></link>.
</para>
<para>
If there are no threads currently spawned, then this function will set threadIndex to 0
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, all was OK and the maximum number of threads is in nThreads.</listitem>
  <listitem><link linkend="kOfxStatFailed"><code>kOfxStatFailed</code></link>, the function failed to return an index</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxMultiThreadSuiteV1_multiThreadIsSpawnedThread">
  <refmeta>
    <refentrytitle><function>OfxMultiThreadSuiteV1::multiThreadIsSpawnedThread</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxMultiThreadSuiteV1::multiThreadIsSpawnedThread</function></refname>
       <refpurpose>Function to enquire if the calling thread was spawned by multiThread</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxMultiThread.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>int</typename><function>(*multiThreadIsSpawnedThread)</function></funcdef>
              <paramdef>void<parameter></parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem> - </listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem>0 if the thread is not one spawned by multiThread</listitem>
  <listitem>1 if the thread was spawned by multiThread</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxMultiThreadSuiteV1_mutexCreate">
  <refmeta>
    <refentrytitle><function>OfxMultiThreadSuiteV1::mutexCreate</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxMultiThreadSuiteV1::mutexCreate</function></refname>
       <refpurpose>Create a mutex</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxMultiThread.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*mutexCreate)</function></funcdef>
              <paramdef>OfxMutexHandle *<parameter>mutex</parameter></paramdef>
              <paramdef>int<parameter>lockCount</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>mutex - where the new handle is returned
</listitem>
<listitem>lockCount - </listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
Creates a new mutex with lockCount locks on the mutex intially set.    
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem>kOfxStatOK - mutex is now valid and ready to go</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxMultiThreadSuiteV1_mutexDestroy">
  <refmeta>
    <refentrytitle><function>OfxMultiThreadSuiteV1::mutexDestroy</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxMultiThreadSuiteV1::mutexDestroy</function></refname>
       <refpurpose>Destroy a mutex</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxMultiThread.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*mutexDestroy)</function></funcdef>
              <paramdef>const OfxMutexHandle<parameter>mutex</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>mutex - </listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
Destroys a mutex intially created by mutexCreate.
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem>kOfxStatOK - if it destroyed the mutex</listitem>
  <listitem>kOfxStatErrBadHandle - if the handle was bad</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxMultiThreadSuiteV1_mutexLock">
  <refmeta>
    <refentrytitle><function>OfxMultiThreadSuiteV1::mutexLock</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxMultiThreadSuiteV1::mutexLock</function></refname>
       <refpurpose>Blocking lock on the mutex</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxMultiThread.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*mutexLock)</function></funcdef>
              <paramdef>const OfxMutexHandle<parameter>mutex</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>mutex - </listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
This trys to lock a mutex and blocks the thread it is in until the lock suceeds. 
</para>
<para>
A sucessful lock causes the mutex's lock count to be increased by one and to block any other calls to lock the mutex until it is unlocked.
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem>kOfxStatOK - if it got the lock</listitem>
  <listitem>kOfxStatErrBadHandle - if the handle was bad</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxMultiThreadSuiteV1_mutexUnLock">
  <refmeta>
    <refentrytitle><function>OfxMultiThreadSuiteV1::mutexUnLock</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxMultiThreadSuiteV1::mutexUnLock</function></refname>
       <refpurpose>Unlock the mutex</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxMultiThread.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*mutexUnLock)</function></funcdef>
              <paramdef>const OfxMutexHandle<parameter>mutex</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>mutex - </listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
This  unlocks a mutex. Unlocking a mutex decreases its lock count by one.
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem>kOfxStatOK if it released the lock</listitem>
  <listitem>kOfxStatErrBadHandle if the handle was bad</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxMultiThreadSuiteV1_mutexTryLock">
  <refmeta>
    <refentrytitle><function>OfxMultiThreadSuiteV1::mutexTryLock</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxMultiThreadSuiteV1::mutexTryLock</function></refname>
       <refpurpose>Non blocking attempt to lock the mutex</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxMultiThread.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*mutexTryLock)</function></funcdef>
              <paramdef>const OfxMutexHandle<parameter>mutex</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>mutex - </listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
This attempts to lock a mutex, if it cannot, it returns and says so, rather than blocking.
</para>
<para>
A sucessful lock causes the mutex's lock count to be increased by one, if the lock did not suceed, the call returns immediately and the lock count remains unchanged.
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem>kOfxStatOK - if it got the lock</listitem>
  <listitem>kOfxStatFailed - if it did not get the lock</listitem>
  <listitem>kOfxStatErrBadHandle - if the handle was bad</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>
