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	MEMORYDIAGNOSTICSMODE : Int {   ESTIMATEONLY,   QUIET,   VERBOSE,   LEAKGRAPH,   PRIVATE_OFF,   PRIVATE_ON }
enum	MEMORYOBSERVERMODE : Int {   LOWMEM_CLEANUP,   LOWMEM_FAILURE,   WARNMEM_LIMIT }
enum	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)
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)
template<typename T >
static MAXON_FUNCTION void	FreeWithDestructor (T *object, void(*destructor)(T *))
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 Char *	GetCriticalLog (Int index, Int *count)
static MAXON_METHOD Int	GetDefinitionCount (EntityBase::TYPE type)
static const MAXON_METHOD 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 const MAXON_METHOD Error *	SetCurrentError (const Error &error)
static const MAXON_METHOD Error *	SetCurrentError (Error &&error)
static const MAXON_METHOD Error *	GetLastError ()
static MAXON_METHOD void	SetDebugError (const Error *preallocated, const Error &error)
static const MAXON_METHOD ErrorInterface *	GetDebugError (const Error *preallocated)
static MAXON_METHOD Result< const Id * >	PrivateGetInternedId (const Id &value)
static MAXON_METHOD void	PrivateFreeInternedId (const Id *ptr)
static StrongReferenceCounter &	GetReferenceCounter (const void *object)
static const MAXON_METHOD Block< const Binary *const > &	GetBinaries ()
static MAXON_METHOD void	PrivateShowSynchronizedHashMapDiagnostics (Int size, Int capacity, const Char *signature)
static const MAXON_METHOD Char *	GetPreferencesPathSuffix ()
static MAXON_METHOD Id	GetApplicationId ()
static MAXON_METHOD void	SetApplicationType (const Char *dna)

Private Member Functions
	MAXON_INTERFACE_NONVIRTUAL (System, MAXON_REFERENCE_STATIC, "net.maxon.interface.system")

Static Private Member Functions
static MAXON_METHOD void	FreeWithDestructorI (void *object, DestructorPointer destruct)

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

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"    )

private

MAXON_ENUM_LIST_CLASS() [1/2]

enum maxon::System::MEMORYDIAGNOSTICSMODE Int MAXON_ENUM_LIST_CLASS

(

MEMORYDIAGNOSTICSMODE

)

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  )

static

Prints debug information into the console window.

Parameters

[in]

s

Char* to print out.

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]	size	Block size in bytes (values < 0 will return nullptr).
[in]	location	MemoryAllocationStructure (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]	size	Block size in bytes (values < 0 will return nullptr).
[in]	location	MemoryAllocationStructure (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]	data	Current memory block (can be nullptr).
[in]	size	New block size in bytes (values < 0 will return nullptr).
[in]	location	MemoryAllocationStructure (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]

data

Memory block address (can be nullptr).

FreeWithDestructor()

static MAXON_FUNCTION void FreeWithDestructor ( T *  object, void(*)(T *)  destructor  )

static

GetAllocSize()

static MAXON_METHOD Int GetAllocSize ( void *  data )

static

Returns the size of a memory block.

Parameters

[in]

data

Memory 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]	mode	See MEMORYDIAGNOSTICSMODE.
[out]	totalAllocation	Used 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]	freePhysicalMemoryEstimate	Used 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]	mode	See MEMORYOBSERVERMODE.
[in]	observer	Observer.

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]

warnMemoryAllocationThreshold

The 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]

index

Index 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]

config

The 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]	index	Index to the log, starting at zero. If the return value is nullptr then no more log entries exist.
[out]	count	Pointer 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]

type

Entity 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 const MAXON_METHOD InterfaceReference* GetVirtualInterfaceReference ( const Id &  idWithoutHash )

static

Returns the virtual references of a given class.

Parameters

[in]

idWithoutHash

Class 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]	type	Entity type. Use EntityBase::TYPE::COUNT for the total number of methods of all (virtual and non-virtual) interfaces.
[in]	eid	Entity 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();
System::ResetDebugErrorObserver(callback);

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]

observer

Observer 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]

observer

The observer to remove.

SetCurrentError() [1/2]

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

static

SetCurrentError() [2/2]

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

static

GetLastError()

static const MAXON_METHOD Error* GetLastError ( )

static

SetDebugError()

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

static

GetDebugError()

static const MAXON_METHOD 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 const MAXON_METHOD Block<const Binary* const>& GetBinaries ( )

static

PrivateShowSynchronizedHashMapDiagnostics()

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

static

GetPreferencesPathSuffix()

static const MAXON_METHOD 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

FreeWithDestructorI()

static MAXON_METHOD void FreeWithDestructorI ( void *  object, DestructorPointer  destruct  )

staticprivate

Parameters

[in]	object	Object/memory block address (guaranteed not to be nullptr).
[in]	destruct	Object destructor (guaranteed not to be nullptr).