c4d.threading

To get an overview of the class members, check out the diagram.

New in version R13.016.

This module constructs higher-level threading interfaces on top of the lower-level thread module.

Classes

• BaseThread
• C4DThread

Functions

• GeThreadLock()
• GeThreadUnlock()

• GeIsMainThread()
• GeGetCPUCount()
• GeGetCurrentThreadId()
• IdentifyThread()
• GeGetCurrentThread()

• GeCheckBackgroundThreadsRunning()
• GeStopBackgroundThreads()
• GeProcessBackgroundThreads()

Threading Information

Programming a lower level thread is not as easy for the most people so this module will help you to minimize the effort to run or handle your code in another Thread. Python 2.6 is shipped with a standard module which already supports a Thread class, but CINEMA 4D and Python use different implementations. You can always 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.

All parts of the execution/drawing pipeline of CINEMA 4D is threaded. This means that all calls to TagData.Draw(), TagData.Execute(), ObjectData.GetVirtualObjects() and ObjectData.Draw() etc. are called within another thread. You must not modify the scene in any case (insertion, change order, etc.) inside these methods. As an exception, modifications are allowed that change the object’s parameters like the position or attributes.

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

Forbidden Functions

For all threaded functions it’s forbidden to:

1. Add an Event.
2. Make any changes to materials.
3. Change the structure of objects attached to the scene.
4. Change parameters of elements attached to the scene (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.

Scene Modifications

Before making modifications in the active scene, for example from a dialog, you always need to call StopAllThreads(). You have to do this even if you yourself are in the main thread,since there could be other threads that read from the scene.

Functions Documentation

c4d.threading.GeThreadLock()

A global semaphore. When you have locked this, 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()

Continue blocked threads after a call to GeThreadLock().

c4d.threading.GeIsMainThread()

Checks if you are in the main thread of CINEMA 4D.

Return type: bool Returns: True if called from the main thread, otherwise False.

c4d.threading.GeGetCPUCount()

Get the number of CPUs in the system.

Return type: int Returns: The number of CPUs.

c4d.threading.GeGetCurrentThreadId()

Returns a unique ID for the current thread. Usually you don’t have to 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) – A thread. 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.GeCheckBackgroundThreadsRunning(typeclass, all)

Allows you to see if any of the threads matching typeclass is running. If typeclass == 0 all threads are checked. If all is True then it also checks background handler with negative priority.

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 and ants (which are always running in a BP selection).

Parameters:

• typeclass (int) – A specific type class, or 0 for all classes.
• all (bool) – If this is True, negative priorities 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 give typeclass. If typeclass == 0 this means all threads. If typeclass is BACKGROUNDHANDLER_TYPECLASS_C4D then flags has the following meaning: (For your own typeclasses you can define flags as you want, it will be routed to the handler function.)

For example GeStopBackgroundThreads() (BACKGROUNDHANDLER_TYPECLASS_C4D, BACKGROUNDHANDLER_FLAGS_EDITORRENDDER) will only stop the editor renderer (if it was running). GeStopBackgroundThreads() (0, BACKGROUNDHANDLERFLAGS_SHUTDOWN) will kill anything running.

Parameters:

• typeclass (int) – A specific type class to stop, or 0 for all classes.
• flags –

  Stop flags:

  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.

c4d.threading.GeProcessBackgroundThreads(typeclass)

This is called by CINEMA 4D when it is idle. It checks with the background handlers if they have something to do.

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