c4d.threading

Programming a lower level thread is not as easy for the most people so this module helps to minimize the effort to run or handle code in another Thread.
Python is shipped with a standard module which already supports a Thread class, but Cinema 4D and Python use different implementations.
Use this module instead of the Python standard module, since all functions in this module are wrapped from the Cinema 4D C++ SDK and therefore stable.

See also

The important Threading Information below.

Threading Information

All parts of the execution/drawing pipeline of Cinema 4D are threaded. This means that the following methods are called within another thread:

Warning

The document must not be modified in any case (insertion, change order, etc.) inside these methods.
Changing the document structure while an expression is evaluated will crash the application!
As an exception, modifications are allowed that change an object’s parameters like the position or attributes.
So the following functions are forbidden inside expressions (tags/nodes):

ObjectData.GetVirtualObjects() is of course allowed to do any modifications that do not modify the document as the object returned is not in the document at that time it may be created/changed in any way.

Forbidden Functions

For all threaded functions it is forbidden to:

  1. Add an event.
  2. Make any changes to materials.
  3. Change the structure of objects attached to the document.
  4. Change parameters of elements attached to the document. (Allowed, but not recommended except for tags.)
  5. Call a Draw() function.
  6. Perform any GUI functionality. (E.g. displaying messages, opening dialogs etc.)
  7. During drawing to do any file operations. (During execution it is allowed.)
  8. Create undos.

Document Modifications

Before making modifications in the active document, for example from a CommandData dialog, always call StopAllThreads(). Do this even if in the main thread, since there could be other threads that read from the document.

Functions Documentation

c4d.threading.GeThreadLock()

Locks using a global semaphore. When locked, any other thread trying to acquire the lock will have to wait. Other threads will continue.

Note

As this blocks all threads it should only be used if and when necessary. A local semaphore is a more elegant and efficient solution to multiple thread data access.

c4d.threading.GeThreadUnlock()

Continues blocked threads after a call to GeThreadLock().

c4d.threading.GeIsMainThread()

Checks if the code is run from within the main thread of Cinema 4D.

Return type:bool
Returns:True if called from the main thread, otherwise False.
c4d.threading.GeIsMainThreadAndNoDrawThread()

New in version R16.038.

Checks if code is run from within the main thread of Cinema 4D and if the main thread does not execute any drawing code currently.

Note

This routine can be used to make sure that no illegal code is called during a drawing operation.
In Cinema 4D the drawing will be started threaded or non-threaded, depending on the situation.
It is not allowed to add e.g. undos or delete objects or materials while the drawing is in progress (this would lead to immediate crashes).
If code calls other routines that are not aware of their context (e.g. some code within a Message() that does not know whether it was called from a drawing thread or during a command call).
GeIsMainThreadAndNoDrawThread() can be used to detect the correct situation.
Return type:bool
Returns:True if called from the main thread and main thread does not execute a drawing operation, otherwise False.
c4d.threading.GeGetCurrentThreadCount()

New in version R16.021.

Gets the number of threads for the current render context.

Return type:int
Returns:The number of current threads.
c4d.threading.GeGetCurrentThreadId()

Returns a unique ID for the current thread.

Note

Usually do not care about this.

Return type:int
Returns:The unique ID for the current thread.
c4d.threading.IdentifyThread(bt)

Identifies a thread’s type.

Parameters:bt (BaseThread) – The thread to identify.
Return type:int
Returns:The thread type:
THREADTYPE_0 None.
THREADTYPE_EDITORREDRAW Editor redraw.
THREADTYPE_RENDEREDITOR Editor render.
THREADTYPE_RENDEREXTERNAL External render.
c4d.threading.GeGetCurrentThread()

Returns the current thread.

Return type:BaseThread
Returns:The current thread.
c4d.threading.GeGetDummyThread()

New in version R17.048.

Returns a dummy thread. The thread’s BaseThread.TestBreak() function always returns False.

Return type:BaseThread
Returns:A dummy thread .
c4d.threading.GeGetEscTestThread()

New in version R17.048.

Returns a dummy thread for escape key testing. The thread’s BaseThread.TestBreak() function returns True when the user presses the escape key.

Return type:BaseThread
Returns:An escape key test thread.
c4d.threading.GeCheckBackgroundThreadsRunning(typeclass, all)

Checks if any of the threads matching typeclass is running.

Parameters:
  • typeclass (int) –
    The type class of the background threads to check. If 0, all threads are checked. Pass BACKGROUNDHANDLER_TYPECLASS_C4D to check Cinema 4D background handlers.

    For example GeCheckBackgroundThreadsRunning(BACKGROUNDHANDLER_TYPECLASS_C4D, True) checks if Cinema 4D is doing anything right now.
    If False were passed it would not check for the external renderer (which are always running in a BodyPaint 3D selection).
  • all (bool) – If True then background handler with negative priority are also checked.
Return type:

bool

Returns:

True if the specified threads are running, otherwise False.

c4d.threading.GeStopBackgroundThreads(typeclass, flags)

Stops all running background threads of the given typeclass.

Parameters:
  • typeclass (int) – The type class of the background threads to stop. If 0, all threads are stopped. Pass BACKGROUNDHANDLER_TYPECLASS_C4D to stop Cinema 4D background handlers.
  • flags (int) –
    If typeclass is BACKGROUNDHANDLER_TYPECLASS_C4D then the following flags can be used:
    BACKGROUNDHANDLERFLAGS_0 None.
    BACKGROUNDHANDLERFLAGS_VIEWREDRAW View redraw.
    BACKGROUNDHANDLERFLAGS_EDITORRENDDER Editor render.
    BACKGROUNDHANDLERFLAGS_MATERIALPREVIEW Material preview.
    BACKGROUNDHANDLERFLAGS_RENDEREXTERNAL Render external.
    BACKGROUNDHANDLERFLAGS_PRIVATE_VIEWREDRAW Private.
    BACKGROUNDHANDLERFLAGS_SHUTDOWN Shutdown.

    GeStopBackgroundThreads(BACKGROUNDHANDLER_TYPECLASS_C4D, BACKGROUNDHANDLER_FLAGS_EDITORRENDDER) only stops the editor renderer (if it was running).
    GeStopBackgroundThreads(0, BACKGROUNDHANDLERFLAGS_SHUTDOWN) kills anything running.

    Pass flags as needed for custom type classes, they will be routed to the background handler function.
c4d.threading.GeProcessBackgroundThreads(typeclass)

Checks the background handlers if they have something to do.

Parameters:typeclass (int) – A specific type class, or 0 for all classes.