Struct LogController
Burst-friendly backend for Logger that contains LoggerHandle, LogMemoryManager, DispatchQueue and is able to answer if this particular LogLevel is supported by this Logger.
Inherited Members
Namespace: Unity.Logging
Syntax
public struct LogController
Constructors
LogController(LoggerHandle, in LogMemoryManagerParameters)
Constructor that initializes MemoryManager and DispatchQueue. Uses LoggerHandle provided by the caller.
Declaration
public LogController(LoggerHandle loggerHandle, in LogMemoryManagerParameters memoryParameters)
Parameters
Type | Name | Description |
---|---|---|
LoggerHandle | loggerHandle | Unique id of the parent Logger |
LogMemoryManagerParameters | memoryParameters | Parameters used to initialize MemoryManager. Could be used to specify particular size of its buffers. |
Fields
DispatchQueue
Double-buffered queue that is used for dispatching LogMessages. DispatchQueue
Declaration
public DispatchQueue DispatchQueue
Field Value
Type | Description |
---|---|
DispatchQueue |
Handle
Unique id of the Logger
Declaration
public LoggerHandle Handle
Field Value
Type | Description |
---|---|
LoggerHandle |
MemoryManager
Memory manager that stores binary representation of structured logging. LogMemoryManager
Declaration
public LogMemoryManager MemoryManager
Field Value
Type | Description |
---|---|
LogMemoryManager |
SyncMode
Current synchronization mode
Declaration
public SyncMode SyncMode
Field Value
Type | Description |
---|---|
SyncMode |
Properties
IsCreated
True if Logging system has been initialized.
Declaration
public readonly bool IsCreated { get; }
Property Value
Type | Description |
---|---|
Boolean |
NeedsStackTrace
True if any sink requested stack trace. If this is false - logging would work faster.
Declaration
public readonly bool NeedsStackTrace { get; }
Property Value
Type | Description |
---|---|
Boolean |
Methods
AddDecorateHandler(FunctionPointer<LoggerManager.OutputWriterDecorateHandler>)
The function that can add function based decorator. Internally used by Unity.Logging.Internal.LogDecorateHandlerScope, better to use that instead. RemoveDecorateHandler(FunctionPointer<LoggerManager.OutputWriterDecorateHandler>)
Declaration
public void AddDecorateHandler(FunctionPointer<LoggerManager.OutputWriterDecorateHandler> func)
Parameters
Type | Name | Description |
---|---|---|
FunctionPointer<Unity.Logging.Internal.LoggerManager.OutputWriterDecorateHandler> | func | Function based decorator to add |
AddSinkStruct(SinkSystemBase)
Creates new sink using SinkSystemBase's ToSinkStruct method
Declaration
public void AddSinkStruct(SinkSystemBase sink)
Parameters
Type | Name | Description |
---|---|---|
SinkSystemBase | sink | SinkSystemBase object |
BeginEditDecoratePayloadHandles(in LogControllerScopedLock, out Int32)
Function that is called by the logging codegeneration.
Used to populate Decorate array. See LogDecorateScope documentation for more details
This function is called before decoration, EndEditDecoratePayloadHandles(ref LogController, Int32) must be called after LogDecorateScope
Declaration
public static LogContextWithDecorator BeginEditDecoratePayloadHandles(in LogControllerScopedLock lock, out int nBefore)
Parameters
Type | Name | Description |
---|---|---|
Unity.Logging.Internal.LogControllerScopedLock | lock | Unity.Logging.Internal.LogControllerScopedLock that controls LogController |
Int32 | nBefore | Current count of Decorations - PayloadHandles at the moment |
Returns
Type | Description |
---|---|
Unity.Logging.Internal.LogContextWithDecorator | Unity.Logging.Internal.LogContextWithDecorator that controls array of Decorations - PayloadHandles |
DecorateHandlerCount()
Returns count of Function-based Decorators (that you can add with Log.Decorate(function) or AddDecorateHandler(FunctionPointer<LoggerManager.OutputWriterDecorateHandler>) and remove with RemoveDecorateHandler(FunctionPointer<LoggerManager.OutputWriterDecorateHandler>)) They will be executed each time log message is created
Declaration
public int DecorateHandlerCount()
Returns
Type | Description |
---|---|
Int32 | Count of Function-based Decorators |
DecoratePayloadsCount()
Returns count of constant Decorators (that you can add with Log.Decorate("name", value)) They will be copied to new log message payload each time log message is created
Declaration
public int DecoratePayloadsCount()
Returns
Type | Description |
---|---|
Int32 | Count of constant Decorators |
DispatchMessage(PayloadHandle, Int64, LogLevel)
Dispatches a LogMessage
Declaration
public void DispatchMessage(PayloadHandle payload, long stacktraceId, LogLevel logLevel)
Parameters
Type | Name | Description |
---|---|---|
PayloadHandle | payload | PayloadHandle of the binary data associated with the message |
Int64 | stacktraceId | Id of the stacktrace connected to the LogMessage, 0 is none |
LogLevel | logLevel | LogLevel of the LogMessage |
Remarks
This method is thread-safe and can be called from any thread context or Job. If successful, the Logging system will take over ownership of the message data and ensure the memory buffer is released after the message has been processed.
EndEditDecoratePayloadHandles(ref LogController, Int32)
Function that is called by the logging codegeneration.
Used to populate Decorate array. See LogDecorateScope documentation for more details
This function is called after decoration, BeginEditDecoratePayloadHandles(in LogControllerScopedLock, out Int32) must be called before LogDecorateScope
Declaration
public static FixedList64Bytes<PayloadHandle> EndEditDecoratePayloadHandles(ref LogController lc, int nBefore)
Parameters
Type | Name | Description |
---|---|---|
LogController | lc | LogController to add decorations to |
Int32 | nBefore | Same variable that was returned in BeginEditDecoratePayloadHandles(in LogControllerScopedLock, out Int32) call |
Returns
Type | Description |
---|---|
FixedList64Bytes<PayloadHandle> | Array of just added Decorations - PayloadHandles |
FlushSync()
Burst-friendly way to immediately and synchronously Update/Flush the DispatchQueue into sinks. This is a slower alternative to LoggerManager.ScheduleUpdate but can be called from Burst / not main thread.
Declaration
[BurstCompile]
public void FlushSync()
HasSinksFor(LogLevel)
Returns true if the LogLevel is supported by at least one SinkSystemBase in this LogController
Declaration
public bool HasSinksFor(LogLevel level)
Parameters
Type | Name | Description |
---|---|---|
LogLevel | level | LogLevel enum |
Returns
Type | Description |
---|---|
Boolean | Returns true if the LogLevel is supported by at least one SinkSystemBase in this LogController |
LogDispatched()
Count of log messages dispatched and waiting to be processed
Declaration
public int LogDispatched()
Returns
Type | Description |
---|---|
Int32 | Count of log messages dispatched and waiting to be processed |
MustBeValid()
Checks that IsCreated == true. Throws otherwise.
Declaration
[Conditional("ENABLE_UNITY_COLLECTIONS_CHECKS")]
[Conditional("UNITY_DOTS_DEBUG")]
public void MustBeValid()
Exceptions
Type | Condition |
---|---|
Exception | Throws if IsCreated == false |
RemoveDecorateHandler(FunctionPointer<LoggerManager.OutputWriterDecorateHandler>)
The function that remove function based decorator that was added by AddDecorateHandler(FunctionPointer<LoggerManager.OutputWriterDecorateHandler>) Internally used by Unity.Logging.Internal.LogDecorateHandlerScope, better to use that instead. AddDecorateHandler(FunctionPointer<LoggerManager.OutputWriterDecorateHandler>)
Declaration
public void RemoveDecorateHandler(FunctionPointer<LoggerManager.OutputWriterDecorateHandler> func)
Parameters
Type | Name | Description |
---|---|---|
FunctionPointer<Unity.Logging.Internal.LoggerManager.OutputWriterDecorateHandler> | func | Function based decorator to remove |
SetMinimalLogLevelForSink(Int32, LogLevel)
Changes the minimal level of the sink
Declaration
public void SetMinimalLogLevelForSink(int sinkId, LogLevel minimalLevel)
Parameters
Type | Name | Description |
---|---|---|
Int32 | sinkId | Id that was returned by AddSinkStruct(SinkSystemBase) |
LogLevel | minimalLevel | New minimal log level for the sink |
Shutdown()
Stops Logging and releases the memory and destroys systems created by LogController.
Declaration
public void Shutdown()
Remarks
This must be called from the main thread (do not call from a Job) after all Logging calls have completed; any log messages "in flight" will be discarded.
IMPORTANT: Accessing the Payload buffer of a log message when Shutdown is called, e.g. during an asynchronous I/O operation, will result in undefined behavior.