Changeset 20841

Show
Ignore:
Timestamp:
09/20/07 11:17:18 (1 year ago)
Author:
patrick
Message:

Document the use of and customization of render thread CPU affinity assignment.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • juggler/branches/2.2/modules/vrjuggler/doc/getting.started.guide/getting.started.guide.xml

    r20777 r20841  
    774774                  successfully.</para> 
    775775 
    776                   <para>On <productname 
    777                   class="registered">Windows</productname>, the Juggler DLLs 
    778                   (<filename>vpr-2_0.dll</filename>, 
    779                   <filename>jccl-1_2.dll</filename>, 
    780                   <filename>vrj-2_2.dll</filename>, etc.) determine on their 
    781                   own where they are installed when they are attached to the 
    782                   application process. As such, the <productname 
    783                   class="registered">Windows</productname> DLLs will 
    784                   automatically set the environment variable(s) that they need 
    785                   to function properly. If an environment variable is already 
    786                   set, then its setting will <emphasis>not</emphasis> be 
    787                   changed by the DLL when it is attached to the application 
     776                  <para>With the release of VR Juggler 2.2.1, it should not be 
     777                  necessary to set <envar>VJ_BASE_DIR</envar> on any platform 
     778                  in order to <emphasis>execute</emphasis> applications. 
     779                  Compiling applications, however, may require the use of 
     780                  <envar>VJ_BASE_DIR</envar>. This varies from application to 
     781                  application.</para> 
     782 
     783                  <para>The reduced need for <envar>VJ_BASE_DIR</envar> is 
     784                  possible because the Juggler shared libraries determine on 
     785                  their own where they are installed when they are attached to 
     786                  the application process. As such, they will automatically 
     787                  set the environment variable(s) that they need to function 
     788                  properly. If an environment variable is already set, then 
     789                  its setting will <emphasis>not</emphasis> be changed by the 
     790                  shared library when it is attached to the application 
    788791                  process.</para> 
    789792 
    …… 
    878881 
    879882            <varlistentry> 
     883               <term>VJ_DRAW_THREAD_AFFINITY</term> 
     884 
     885               <listitem> 
     886                  <para>VR Juggler 2.2.1 introduced the ability for Linux and 
     887                  IRIX users to direct processor affinity for render threads 
     888                  created by the OpenGL Draw Manager. The default way of doing 
     889                  this is to create a multi-pipe/multi-threaded configuration 
     890                  and then set the environment variable 
     891                  <envar>VJ_DRAW_THREAD_AFFINITY</envar> to be a 
     892                  space-separated list of integers identifying the processors 
     893                  in the machine. The optimal setting for this environment 
     894                  variable is likely to vary with hardware and with 
     895                  applications. If more render threads are created than there 
     896                  are processors available, the OpenGL Draw Manager starts 
     897                  over at the beginning of the processor ID list.</para> 
     898 
     899                  <tip> 
     900                     <para>With a multi-processor, multi-core computer, it 
     901                     will generally be best to separate rener threads by 
     902                     processor first and by core second. For example, on a 
     903                     dual processor, dual core machine, a setting of <quote>0 
     904                     2 1 3</quote> is likely to give good results. In this 
     905                     case, render thread 0 will be assigned to processor 0, 
     906                     render thread 1 to processor 2, and so on.</para> 
     907                  </tip> 
     908 
     909                  <note> 
     910                     <para>It is possible to use a value less than zero for a 
     911                     processor ID when setting this environment variable. 
     912                     Doing so will disable processor affinity for that 
     913                     particular rendering thread.</para> 
     914                  </note> 
     915 
     916                  <para>Be aware that the use of this environment variable is 
     917                  optional and that application programmers are free to define 
     918                  their own render thread affinity algorithm that may not use 
     919                  this environment variable at all. For more details on how to 
     920                  do this, refer to the VR Juggler <emphasis>Programmer's 
     921                  Guide</emphasis>.</para> 
     922               </listitem> 
     923            </varlistentry> 
     924 
     925            <varlistentry> 
    880926               <term>VJ_CFG_PATH</term> 
    881927 

  • juggler/branches/2.2/modules/vrjuggler/doc/programmer.guide/programmer.guide.xml

    r20723 r20841  
    1096010960         important, interesting, and worthwhile topics nonetheless.</para> 
    1096110961 
     10962         <section> 
     10963            <title>Customizing Render Thread Processor Affinity</title> 
     10964 
     10965            <para>VR Juggler 2.2.1 introduced the feature of adjustable render 
     10966            thread processor affinity for Linux and IRIX users of the OpenGL 
     10967            Draw Manager. The default mechanism for defining processor 
     10968            affinity is based on an environment variable and the use of a 
     10969            simple round-robin scheme for the case of having more graphics 
     10970            pipes than processors. More tailored uses of render thread 
     10971            processor affinity can be achieved by giving the OpenGL Draw 
     10972            Manager a custom affinity assignment algorithm. That will be the 
     10973            topic of this section.</para> 
     10974 
     10975            <para>The OpenGL Draw Manager class 
     10976            <classname>vrj::GlDrawManager</classname> has a method named 
     10977            <methodname>setCpuAffinityStrategy()</methodname> that takes as 
     10978            its argument a callable object. This is encapsulated using a 
     10979            Boost.Function object of type <type>boost::function&lt;int (const 
     10980            unsigned int)&gt;</type>, which in English is a function that 
     10981            takes a single constant unsigned integer (the pipe identifier) and 
     10982            returns a signed integer (the processor identifier). Anything that 
     10983            can be encapsulated by a Boost.Function object can be used. That 
     10984            includes a pointer to a C function, a pointer to a static C++ 
     10985            class member function, a value returned by 
     10986            <function>boost::bind()</function>, or an instance of a class that 
     10987            overloads <methodname>operator()</methodname>. This usage 
     10988            implements the Strategy Pattern where functionality is plugged in 
     10989            at run time. The default behavior is to use an instance of 
     10990            <classname>vrj::CpuAffinityFromEnv</classname>, assigned in the 
     10991            <classname>vrj::GlDrawManager</classname> constructor.</para> 
     10992 
     10993            <para>The job of this callable object is to map the pipe 
     10994            identifier to the processor to which affinity will be assigned for 
     10995            the render thread of the pipe. The processor identifier is a 
     10996            signed integer so that a negative value can be used to indicate 
     10997            that no affinity should be assigned for the render thread of the 
     10998            pipe. The exact means by which it accomplishes this can vary, and 
     10999            that is the power of the Strategy Pattern in this context.</para> 
     11000 
     11001            <para>To provide a customized processor affinity assignment 
     11002            algorithm, 
     11003            <methodname>vrj::GlDrawManager::setCpuAffinityStrategy()</methodname> 
     11004            must be invoked at the correct time. The OpenGL Draw Manager uses 
     11005            whatever affinity assignment algorithm it has as soon as it 
     11006            determines that vrj::GlPipe objects need to be created. This is 
     11007            done as part of the VR Juggler run-time reconfiguration process. 
     11008            Therefore, to guarantee that all pipes use the customized 
     11009            algorithm, 
     11010            <methodname>vrj::GlDrawManager::setCpuAffinityStrategy()</methodname> 
     11011            must be called before calling 
     11012            <methodname>vrj::Kernel::start()</methodname>, the method that 
     11013            starts the VR Juggler kernel control loop. Since the kernel 
     11014            control loop is normally started in the application 
     11015            <function>main()</function> function, the most likely place for a 
     11016            call to 
     11017            <methodname>vrj::GlDrawManager::setCpuAffinityStrategy()</methodname> 
     11018            is also in <function>main()</function>. Of course, this can vary 
     11019            depending on how VR Juggler is being used, so the most important 
     11020            thing to understand is that it must happen 
     11021            <emphasis>before</emphasis> 
     11022            <methodname>vrj::Kernel::start()</methodname> is called.</para> 
     11023         </section> 
     11024 
    1096211025         <section id="section.custom.delegate"> 
    1096311026            <title>Making a Custom <classname>NSApplication</classname>