CRhinoWorkerThread Class Reference

#include <RhinoSdkWorkerThread.h>

Public Member Functions
	CRhinoWorkerThread ()
virtual	~CRhinoWorkerThread ()
virtual void	CleanUpRuntimeCaches (bool bDelete)=0
bool	Run (const wchar_t *sCommandLineMessage)
virtual void	Worker ()=0

Static Public Member Functions
static void	CancelWorker ()
static void	DecrementFakeWorkerThreads (void)
static void	EnableWorkerThreads (int bEnable=true)
static void	IncrementFakeWorkerThreads (void)
static bool	IsRunning ()
static bool	KeepRunning ()
static ON__UINT_PTR	ThreadId ()
static ON__UINT64	WorkerContextSerialNumber ()
static bool	WorkerThreadsEnabled ()

Constructor & Destructor Documentation

CRhinoWorkerThread()

CRhinoWorkerThread::CRhinoWorkerThread

(

)

~CRhinoWorkerThread()

virtual CRhinoWorkerThread::~CRhinoWorkerThread ( )

virtual

Member Function Documentation

CancelWorker()

static void CRhinoWorkerThread::CancelWorker ( )

static

Description: Call CancelWorker() to cancel a worker thread. If a dialog runs a time consuming task, then you may want to add a cancel button to the dialog and call CRhinoWorkerThread::CancelWorker if the user presses that button. Remarks: If Worker() is running in a thread, this sets the thread's memory pool flags so ExitThread() will be called on next onmalloc(), oncalloc(), onrealloc(), onfree(), new, or delete.

CleanUpRuntimeCaches()

virtual void CRhinoWorkerThread::CleanUpRuntimeCaches ( bool  bDelete )

pure virtual

Description: Cleans up runtime caches that exist on any objects whose memory belongs on the main thread stack or heap but whose runtime cache may be created in worker thread's stack or worker heap. Basically, this function needs to call the ON_Object::DestroyRuntimeCache() member functions of breps, curves and surfaces that exist in the main thread's stack or heap but are used in closest point or intersection calculations performed in the Worker() function.

Parameters: bDelete - [in] pass this parameter on to the ON_Object::DestroyRuntimeCache(bDelete) function. Basically, if bDelete is true, then you should free/delete runtime cache information that is on the heap. If bDelete is false, then you should simply zero out pointers on main heap/stack classes that point to memory allocated from the worker pool. If this is confusing, then you need to get help before you check in anything using cancel threads.

Remarks: It is critical to do this right. If you don't we end up with hrd to repeat crashes that happen one to many commands after the actual cancel event.

This function is pure virtual so that any developer using a cancel thread is forced to think about cleaning up runtime memory caches. If you are at all confused, then please ask for help or do not use cancel threads.

Test thoroughly before checking in.

DecrementFakeWorkerThreads()

static void CRhinoWorkerThread::DecrementFakeWorkerThreads ( void  )

static

EnableWorkerThreads()

static void CRhinoWorkerThread::EnableWorkerThreads ( int  bEnable = true )

static

Description: By default, worker threads are enabled. If you need to user Purify or debug something that happens in a CRhinoWorkerThread::Worker override, then call CRhinoWorkerThread::EnableWorkerThreads(FALSE) and your task will be much easier. See Also: CRhinoWorkerThread::WorkerThreadsEnabled

IncrementFakeWorkerThreads()

static void CRhinoWorkerThread::IncrementFakeWorkerThreads ( void  )

static

Description: These functions are used when a custom built worker-thread style mechanism is running, and the developer wants Rhino to act as though a real worker thread is running. The UI will be disabled and views will not draw. Of course, it is absolutely essential that these functions are called in pairs.

IsRunning()

static bool CRhinoWorkerThread::IsRunning ( )

static

static function interface to the query and manage the thread. There may be nested calls to CWorkerThread::Run but there is only a single Windows worker thread at any one time. Returns:
TRUE if a worker thread is running.

KeepRunning()

static bool CRhinoWorkerThread::KeepRunning ( )

static

Description: Call this function in Worker() member functions that that do not regularly allocate memory.
Example:

    for(...)
    {

/ loop with LOTS of calculation and no memory allocation if ( !CRhinoWorkerThread::KeepRunning() ) { / thread will die soon, just bail out return; } }

Returns: TRUE if you should keep going. FALSE if you should bail out.

Run()

bool CRhinoWorkerThread::Run

(

const wchar_t *

sCommandLineMessage

)

Description: Runs the Worker() task in a thread that the user can cancel by pressing the "Esc" key. Returns: TRUE if Worker() ask runs to completion. FALSE if Worker() task is canceled. See Also: CRhinoWorkerThread::Worker

ThreadId()

static ON__UINT_PTR CRhinoWorkerThread::ThreadId ( )

static

Returns; Worker thread id or zero.

Worker()

virtual void CRhinoWorkerThread::Worker ( )

pure virtual

Description: Override Worker to perform time consuming calculations that the user can immediately cancel by pressing the "Esc" key. Use member variables in your derived class to pass information in and out of your Worker function. Example:

    class CMyWorker : public CRhinoWorkerThread
    {
    public:
      CMyWorker();
      ~CMyWorker();
      void Worker();

/ override of pure virtual runtime cache cleaner void CleanUpRuntimeCaches( bool bDelete );

/ use member variables to pass information to/from worker };

void CMyWorker::Worker() { / NEVER EVER Call ExitThread() in your worker function!!!

/ See the CRhinoWorkerThread::KeepRunning() example if / if you have a time consuming loop with no memory / allocation.

        ...
      }

      void CMyWorker::CleanUpRuntimeCaches( bool bDelete )
      {

/ Call the virtual ON_Object::DestroyRuntimeCache(bDelete) / on object that are in the main thread.

/ Be sure to get this right, or we get hard to trace / crashes that happen in other places after a cancel. } ...

{ ... CMyWorker worker; ... BOOL32 bCompletedTask = worker.Run( RhLocalizeString( L"Calculating widget hyperextension coefficient", 43572) ); if ( !bCompletedTask ) { / User canceled task - carefully destroy worker } else { / harvest results from worker membr variables } }

Remarks: Do NOT create dialogs and do NOT call Rhino SDK functions in a Worker() function except for those listed below.

You may call the following Rhino SDK functions in a Worker function: CRhinoApp.Print CRhinoDoc::AddPointObject CRhinoDoc::AddPointCloudObject CRhinoDoc::AddCurveObject CRhinoDoc::AddSurfaceObject CRhinoDoc::AddMeshObject CRhinoDoc::AddBrepObject

Other than adding objects, don't mess with the document, application, or views in a Worker() function.

WorkerContextSerialNumber()

static ON__UINT64 CRhinoWorkerThread::WorkerContextSerialNumber ( )

static

Returns; Worker thread id or zero.

WorkerThreadsEnabled()

static bool CRhinoWorkerThread::WorkerThreadsEnabled ( )

static

Returns: TRUE if the use of worker threads is enabled. FALSE if the use of worker threads has been disabled. Remarks: By default, the use of worker threads is enabled. When using Purify or doing delicate debugging of a Worker function, disabling the use of separate threads can be helpful. See Also: CRhinoWorkerThread::EnableWorkerThreads