c4d.threading ¶

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

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.

Classes ¶

• BaseThread
• C4DThread

Functions ¶

• GeThreadLock()
• GeThreadUnlock()

• GeIsMainThread()
• GeIsMainThreadAndNoDrawThread()
• GeGetCurrentThreadCount()
• GeGetCurrentThreadId()
• IdentifyThread()
• GeGetCurrentThread()
• GeGetDummyThread()
• GeGetEscTestThread()

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

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:

• TagData.Draw() TagData.Execute()
• ObjectData.GetVirtualObjects() ObjectData.Execute() ObjectData.Draw() ObjectData.DrawShadow()
• other Draw() / Execute()

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):
- GeListNode.InsertBefore() - GeListNode.InsertAfter() - GeListNode.InsertUnder() - GeListNode.InsertUnderLast() - GeListNode.Remove()

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 ( ) ¶

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. 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 your 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.

Get the number of threads for the current render context.

Return type:	int
Returns:	The number of threads for the current render context.

c4d.threading. GeGetCurrentThreadId ( ) ¶

Returns a unique ID for the current thread. Usually you do not 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. GeGetDummyThread ( ) ¶

New in version R17.048.

Returns a dummy thread ( BaseThread.TestBreak() will always return False ).

Return type:	BaseThread
Returns:	A dummy thread.

c4d.threading. GeGetEscTestThread ( ) ¶

New in version R17.048.

Returns a dummy thread for escape key testing ( BaseThread.TestBreak() will return True when the user presses the Esc key).

Return type:	BaseThread
Returns:	An escape key test 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.

Table Of Contents

• c4d.threading
  • Classes
  • Functions
  • Threading Information
    • Forbidden Functions
    • Document Modifications
  • Functions Documentation