System Class Reference

#include <system.h>

Detailed Description

Application wide system functions. Do not use any of those functions directly. Implement this interface to link against the kernel library.

Public Types

enum class  MEMORYDIAGNOSTICSMODE : Int {
  ESTIMATEONLY ,
  QUIET ,
  VERBOSE ,
  LEAKGRAPH ,
  PRIVATE_OFF ,
  PRIVATE_ON ,
  PRIVATE_GARBAGE
}
 
enum class  MEMORYOBSERVERMODE : Int {
  LOWMEM_CLEANUP ,
  LOWMEM_FAILURE ,
  WARNMEM_LIMIT
}
 
enum class  SPECIALBEHAVIOR : Int {
  NONE ,
  OMIT_HELP ,
  DONTWARN_MISSINGARGUMENTS
}
 

Public Member Functions

enum maxon::System::MEMORYDIAGNOSTICSMODE Int MAXON_ENUM_LIST_CLASS (MEMORYDIAGNOSTICSMODE)
 
enum maxon::System::MEMORYOBSERVERMODE Int MAXON_ENUM_LIST_CLASS (MEMORYOBSERVERMODE)
 
enum maxon::System::SPECIALBEHAVIOR Int MAXON_ENUM_FLAGS_CLASS (SPECIALBEHAVIOR)
 

Static Public Member Functions

static MAXON_METHOD void _ConsoleOutput (const Char *s, const SourceLocation &loc, OUTPUT flags=OUTPUT::NONE)
 
static MAXON_METHOD OUTPUT GetConsoleOutputType ()
 
static MAXON_METHOD void * Alloc (Int size, const SourceLocation &location)
 
static MAXON_METHOD void * AllocClear (Int size, const SourceLocation &location)
 
static MAXON_METHOD void * Realloc (void *data, Int size, const SourceLocation &location)
 
static MAXON_METHOD void Free (const void *data)
 
static MAXON_METHOD Int GetAllocSize (void *data)
 
static MAXON_METHOD Int MemoryDiagnostics (MEMORYDIAGNOSTICSMODE mode=MEMORYDIAGNOSTICSMODE::VERBOSE, Int *totalAllocation=nullptr, Int *freePhysicalMemoryEstimate=nullptr)
 
static MAXON_METHOD Bool MemoryAddObserver (MEMORYOBSERVERMODE mode, Delegate< void()> &&observer)
 
static MAXON_METHOD void SetMemoryAllocationThreshold (UInt warnMemoryAllocationThreshold)
 
static MAXON_METHOD Float64 GetCustomTimer ()
 
static MAXON_METHOD Int GetConfigurationCount ()
 
static MAXON_METHOD Bool GetConfiguration (Int index, ConfigInit &config)
 
static MAXON_METHOD Bool ConfigurationRegister (const ConfigInit &config)
 
static MAXON_METHOD CharGetCriticalLog (Int index, Int *count)
 
static MAXON_METHOD Int GetDefinitionCount (EntityBase::TYPE type)
 
static MAXON_METHOD const InterfaceReference * GetVirtualInterfaceReference (const Id &idWithoutHash)
 
static MAXON_METHOD EntityDefinition * FindDefinition (EntityBase::TYPE type, const Id &eid)
 
static MAXON_METHOD void * SetDebugErrorObserver (Delegate< void(const ErrorInterface *)> &&observer)
 
static MAXON_METHOD void ResetDebugErrorObserver (void *observer)
 
static MAXON_METHOD const Error * SetCurrentError (const Error &error)
 
static MAXON_METHOD const Error * SetCurrentError (Error &&error)
 
static MAXON_METHOD const Error * GetLastError ()
 
static MAXON_METHOD void SetDebugError (const Error *preallocated, const Error &error)
 
static MAXON_METHOD const ErrorInterfaceGetDebugError (const Error *preallocated)
 
static MAXON_METHOD Result< const Id * > PrivateGetInternedId (const Id &value)
 
static MAXON_METHOD void PrivateFreeInternedId (const Id *ptr)
 
static StrongReferenceCounterGetReferenceCounter (const void *object)
 
static MAXON_METHOD const Block< const Binary *const > & GetBinaries ()
 
static MAXON_METHOD void PrivateShowSynchronizedHashMapDiagnostics (Int size, Int capacity, const Char *signature)
 
static MAXON_METHOD const CharGetPreferencesPathSuffix ()
 
static MAXON_METHOD Id GetApplicationId ()
 
static MAXON_METHOD void SetApplicationType (const Char *dna)
 
static MAXON_METHOD Bool PrivateInitExternalDependency (InitMTable initSystemTable, Binary *externalDependency)
 
static MAXON_METHOD Bool PrivateResetExternalDependency (const Block< Tuple< Id, const char *, void * >> &safeShutdownMethods, Binary *externalDependency)
 
static MAXON_METHOD UniqueHash PrivateGetUniqueHashCode (const Byte *ptr, Int count)
 
static MAXON_METHOD void PrivateHasherInitialize (UniqueHasher &state)
 
static MAXON_METHOD void PrivateHasherCombine (UniqueHasher &state, const Byte *ptr, Int count)
 
static MAXON_METHOD void PrivateHasherCombine (UniqueHasher &state, const UniqueHash &hash)
 
static MAXON_METHOD UniqueHash PrivateHasherFinalize (const UniqueHasher &state)
 
static MAXON_METHOD void PrivateFreeWithDestructor (const void *object, DestructorPointer destruct)
 

Private Member Functions

 MAXON_INTERFACE_NONVIRTUAL (System, MAXON_REFERENCE_STATIC, "net.maxon.interface.system", MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel"))
 

Member Enumeration Documentation

◆ MEMORYDIAGNOSTICSMODE

enum MEMORYDIAGNOSTICSMODE : Int
strong
Enumerator
ESTIMATEONLY 

Just return current total allocation estimate.

QUIET 

Just return allocation numbers.

VERBOSE 

Additional details will be sent to the console.

LEAKGRAPH 

Create a memory leak graph (circular references).

PRIVATE_OFF 
PRIVATE_ON 
PRIVATE_GARBAGE 

◆ MEMORYOBSERVERMODE

enum MEMORYOBSERVERMODE : Int
strong
Enumerator
LOWMEM_CLEANUP 

The observer should free resources/caches and then the allocator will retry.

LOWMEM_FAILURE 

An allocation failed (even retry didn't change that).

WARNMEM_LIMIT 

The allocations exceed a user specified amount of memory.

◆ SPECIALBEHAVIOR

enum SPECIALBEHAVIOR : Int
strong
Enumerator
NONE 
OMIT_HELP 

If set "-help" will not start help mode of the underlying base system, whereas "help" will. This is legacy behavior for C4D.

DONTWARN_MISSINGARGUMENTS 

If set there will be no output in the console if an argument is passed but not defined in the code.

Member Function Documentation

◆ MAXON_INTERFACE_NONVIRTUAL()

MAXON_INTERFACE_NONVIRTUAL ( System  ,
MAXON_REFERENCE_STATIC  ,
"net.maxon.interface.system"  ,
MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel")   
)
private

◆ MAXON_ENUM_LIST_CLASS() [1/2]

◆ MAXON_ENUM_LIST_CLASS() [2/2]

enum maxon::System::MEMORYOBSERVERMODE Int MAXON_ENUM_LIST_CLASS ( MEMORYOBSERVERMODE  )

◆ MAXON_ENUM_FLAGS_CLASS()

enum maxon::System::SPECIALBEHAVIOR Int MAXON_ENUM_FLAGS_CLASS ( SPECIALBEHAVIOR  )

◆ _ConsoleOutput()

static MAXON_METHOD void _ConsoleOutput ( const Char s,
const SourceLocation loc,
OUTPUT  flags = OUTPUT::NONE 
)
static

Prints debug information into the console window.

Parameters
[in]sChar* to print out.
[in]locThe source location.
[in]flagsOutput flags.

◆ GetConsoleOutputType()

static MAXON_METHOD OUTPUT GetConsoleOutputType ( )
static

Retrieves which types of output shall be supported.

Returns
Diagnostic, warning and/or critical output.

◆ Alloc()

static MAXON_METHOD void* Alloc ( Int  size,
const SourceLocation location 
)
static

Allocates a memory block, does not clear memory (similar to malloc). The memory is not cleared, it may contain a certain byte pattern in debug mode.

Parameters
[in]sizeBlock size in bytes (values < 0 will return nullptr).
[in]locationMemoryAllocationStructure (filled out by a define).
Returns
Memory block address or nullptr.

◆ AllocClear()

static MAXON_METHOD void* AllocClear ( Int  size,
const SourceLocation location 
)
static

Allocates a memory block and clears it (similar to calloc).

Parameters
[in]sizeBlock size in bytes (values < 0 will return nullptr).
[in]locationMemoryAllocationStructure (filled out by a define).
Returns
Memory block address or nullptr.

◆ Realloc()

static MAXON_METHOD void* Realloc ( void *  data,
Int  size,
const SourceLocation location 
)
static

Resizes a memory block (similar to realloc). The additional memory is not cleared, it may contain a certain byte pattern in debug mode.

Parameters
[in]dataCurrent memory block (can be nullptr).
[in]sizeNew block size in bytes (values < 0 will return nullptr).
[in]locationMemoryAllocationStructure (filled out by a define).
Returns
Memory block address or nullptr if resize is not possible (p is still valid in this case).

◆ Free()

static MAXON_METHOD void Free ( const void *  data)
static

Frees a memory block (free).

Parameters
[in]dataMemory block address (can be nullptr).

◆ GetAllocSize()

static MAXON_METHOD Int GetAllocSize ( void *  data)
static

Returns the size of a memory block.

Parameters
[in]dataMemory block address (can be nullptr, but otherwise must be valid).
Returns
Size of the allocated block in bytes.

◆ MemoryDiagnostics()

static MAXON_METHOD Int MemoryDiagnostics ( MEMORYDIAGNOSTICSMODE  mode = MEMORYDIAGNOSTICSMODE::VERBOSE,
Int totalAllocation = nullptr,
Int freePhysicalMemoryEstimate = nullptr 
)
static

Returns information about memory usage and optionally prints details to the console.

Parameters
[in]modeSee MEMORYDIAGNOSTICSMODE.
[out]totalAllocationUsed to return the total amount of memory allocated including blocks being cached, used for management and so on. This might be considerably bigger than what was allocated by the application.
[out]freePhysicalMemoryEstimateUsed to return a very rough estimate of the free physical memory (if any).
Returns
Memory allocated by the application in bytes.

◆ MemoryAddObserver()

static MAXON_METHOD Bool MemoryAddObserver ( MEMORYOBSERVERMODE  mode,
Delegate< void()> &&  observer 
)
static

Adds an observer for low memory situations. The observer will be active until shutdown.

Parameters
[in]modeSee MEMORYOBSERVERMODE.
[in]observerObserver.
Returns
True on success.

◆ SetMemoryAllocationThreshold()

static MAXON_METHOD void SetMemoryAllocationThreshold ( UInt  warnMemoryAllocationThreshold)
static

Sets the threshold value when observers of mode MEMORYOBSERVERMODE::WARNMEM_LIMIT will be executed. Calling the function again overwrites the older value.

Parameters
[in]warnMemoryAllocationThresholdThe value when the observer will be executed.

◆ GetCustomTimer()

static MAXON_METHOD Float64 GetCustomTimer ( )
static

Returns the current system time which is being used by the Timer class.

Returns
Seconds of the system time.

◆ GetConfigurationCount()

static MAXON_METHOD Int GetConfigurationCount ( )
static

Returns the number of configuration values registered with ConfigurationRegister

Returns
Number of configuration values.

◆ GetConfiguration()

static MAXON_METHOD Bool GetConfiguration ( Int  index,
ConfigInit &  config 
)
static

Gets the configuration value by a given index.

Parameters
[in]indexIndex of the configuration value. 0 <= index < GetConfigurationCount()
Returns
True on success or false if the index is out of range.

◆ ConfigurationRegister()

static MAXON_METHOD Bool ConfigurationRegister ( const ConfigInit &  config)
static

Registers a configuration value ConfigValues with the main application.

Parameters
[in]configThe configuration value and related data (default, limits etc.).
Returns
Success of the registration.

◆ GetCriticalLog()

static MAXON_METHOD Char* GetCriticalLog ( Int  index,
Int count 
)
static

Reads information from the critical log (which is automatically stored in memory). It contains messages that were generated calling CriticalOutput(). THREADSAFE.

Parameters
[in]indexIndex to the log, starting at zero. If the return value is nullptr then no more log entries exist.
[out]countPointer to a value that will receive the number of log entries or nullptr.
Returns
C-Style string containing the critical message or nullptr if no log entry exists for this index.

◆ GetDefinitionCount()

static MAXON_METHOD Int GetDefinitionCount ( EntityBase::TYPE  type)
static

Returns the total number of definitions for the given entity type. This is used for statistics about the complexity of the whole application.

Parameters
[in]typeEntity type. Use EntityBase::TYPE::COUNT for the total number of methods of all (virtual and non-virtual) interfaces.
Returns
Number of definitions of the given type.

◆ GetVirtualInterfaceReference()

static MAXON_METHOD const InterfaceReference* GetVirtualInterfaceReference ( const Id idWithoutHash)
static

Returns the virtual references of a given class.

Parameters
[in]idWithoutHashClass ID without hash.
Returns
Found interface references

◆ FindDefinition()

static MAXON_METHOD EntityDefinition* FindDefinition ( EntityBase::TYPE  type,
const Id eid 
)
static

Returns the definition of the given entity type.

Parameters
[in]typeEntity type. Use EntityBase::TYPE::COUNT for the total number of methods of all (virtual and non-virtual) interfaces.
[in]eidEntity id.
Returns
Found EntityDefinition or nullptr if no entity was found with the given name or type.

◆ SetDebugErrorObserver()

static MAXON_METHOD void* SetDebugErrorObserver ( Delegate< void(const ErrorInterface *)> &&  observer)
static

Sets a callback which shall be invoked when an error occurs. This should be used only for debugging purposes. For example, if you want to have a DebugStop on any error during a function call, you can write:

void* callback = System::SetDebugErrorObserver([] (const ErrorInterface* error) { DiagnosticOutput("@", error); DebugStop(); });
SomeFunctionToDebug();
static MAXON_METHOD void * SetDebugErrorObserver(Delegate< void(const ErrorInterface *)> &&observer)
static MAXON_METHOD void ResetDebugErrorObserver(void *observer)
PyObject * error
Definition: codecs.h:206
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:170
#define DebugStop(...)
Definition: debugdiagnostics.h:225
PyObject * callback
Definition: weakrefobject.h:59

You could even make the DebugStop() depend on the type of the error by checking the type of the error parameter.

You should clear the error callback after the code to debug by calling ResetErrorCallback().

Warning
This method is not thread-safe.
Parameters
[in]observerObserver for errors.
Returns
Pointer to the installed observer or nullptr on failure.

◆ ResetDebugErrorObserver()

static MAXON_METHOD void ResetDebugErrorObserver ( void *  observer)
static

Resets a previously set error callback.

Warning
This method is not thread-safe.
See also
SetErrorCallback
Parameters
[in]observerThe observer to remove.

◆ SetCurrentError() [1/2]

static MAXON_METHOD const Error* SetCurrentError ( const Error &  error)
static

◆ SetCurrentError() [2/2]

static MAXON_METHOD const Error* SetCurrentError ( Error &&  error)
static

◆ GetLastError()

static MAXON_METHOD const Error* GetLastError ( )
static

◆ SetDebugError()

static MAXON_METHOD void SetDebugError ( const Error *  preallocated,
const Error &  error 
)
static

◆ GetDebugError()

static MAXON_METHOD const ErrorInterface* GetDebugError ( const Error *  preallocated)
static

◆ PrivateGetInternedId()

static MAXON_METHOD Result<const Id*> PrivateGetInternedId ( const Id value)
static
Returns
Nullptr indicates OutOfMemory.

◆ PrivateFreeInternedId()

static MAXON_METHOD void PrivateFreeInternedId ( const Id ptr)
static

◆ GetReferenceCounter()

static StrongReferenceCounter& GetReferenceCounter ( const void *  object)
static

Returns the reference counter for classes which do not implement custom AddReference/RemoveReference methods.

◆ GetBinaries()

static MAXON_METHOD const Block<const Binary* const>& GetBinaries ( )
static

Deprecated. Will return an empty block.

◆ PrivateShowSynchronizedHashMapDiagnostics()

static MAXON_METHOD void PrivateShowSynchronizedHashMapDiagnostics ( Int  size,
Int  capacity,
const Char signature 
)
static

◆ GetPreferencesPathSuffix()

static MAXON_METHOD const Char* GetPreferencesPathSuffix ( )
static

◆ GetApplicationId()

static MAXON_METHOD Id GetApplicationId ( )
static

Returns the kind of application. Common definitions can be found in APPLICATIONID.

◆ SetApplicationType()

static MAXON_METHOD void SetApplicationType ( const Char dna)
static

◆ PrivateInitExternalDependency()

static MAXON_METHOD Bool PrivateInitExternalDependency ( InitMTable  initSystemTable,
Binary *  externalDependency 
)
static

◆ PrivateResetExternalDependency()

static MAXON_METHOD Bool PrivateResetExternalDependency ( const Block< Tuple< Id, const char *, void * >> &  safeShutdownMethods,
Binary *  externalDependency 
)
static

◆ PrivateGetUniqueHashCode()

static MAXON_METHOD UniqueHash PrivateGetUniqueHashCode ( const Byte ptr,
Int  count 
)
static

◆ PrivateHasherInitialize()

static MAXON_METHOD void PrivateHasherInitialize ( UniqueHasher state)
static

◆ PrivateHasherCombine() [1/2]

static MAXON_METHOD void PrivateHasherCombine ( UniqueHasher state,
const Byte ptr,
Int  count 
)
static

◆ PrivateHasherCombine() [2/2]

static MAXON_METHOD void PrivateHasherCombine ( UniqueHasher state,
const UniqueHash hash 
)
static

◆ PrivateHasherFinalize()

static MAXON_METHOD UniqueHash PrivateHasherFinalize ( const UniqueHasher state)
static

◆ PrivateFreeWithDestructor()

static MAXON_METHOD void PrivateFreeWithDestructor ( const void *  object,
DestructorPointer  destruct 
)
static
Parameters
[in]objectObject/memory block address (guaranteed not to be nullptr).
[in]destructObject destructor (guaranteed not to be nullptr).