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

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Unity.Logging

Assembly: Unity.Logging.dll

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 bool IsCreated { get; }

Property Value

Type	Description
bool

NeedsStackTrace

True if any sink requested stack trace. If this is false - logging would work faster.

Declaration

public bool NeedsStackTrace { get; }

Property Value

Type	Description
bool

Methods

AddDecorateHandler(FunctionPointer<OutputWriterDecorateHandler>)

The function that can add function based decorator. Internally used by LogDecorateHandlerScope, better to use that instead. RemoveDecorateHandler(FunctionPointer<OutputWriterDecorateHandler>)

Declaration

public void AddDecorateHandler(FunctionPointer<LoggerManager.OutputWriterDecorateHandler> func)

Parameters

Type	Name	Description
FunctionPointer<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 int)

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, int) must be called after LogDecorateScope

Declaration

public static LogContextWithDecorator BeginEditDecoratePayloadHandles(in LogControllerScopedLock @lock, out int nBefore)

Parameters

Type	Name	Description
LogControllerScopedLock	lock	LogControllerScopedLock that controls LogController
int	nBefore	Current count of Decorations - PayloadHandles at the moment

Returns

Type	Description
LogContextWithDecorator	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<OutputWriterDecorateHandler>) and remove with RemoveDecorateHandler(FunctionPointer<OutputWriterDecorateHandler>)) They will be executed each time log message is created

Declaration

public int DecorateHandlerCount()

Returns

Type	Description
int	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
int	Count of constant Decorators

DispatchMessage(PayloadHandle, long, 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
long	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, int)

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 int) 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
int	nBefore	Same variable that was returned in BeginEditDecoratePayloadHandles(in LogControllerScopedLock, out int) 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
bool	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
int	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<OutputWriterDecorateHandler>)

The function that remove function based decorator that was added by AddDecorateHandler(FunctionPointer<OutputWriterDecorateHandler>) Internally used by LogDecorateHandlerScope, better to use that instead. AddDecorateHandler(FunctionPointer<OutputWriterDecorateHandler>)

Declaration

public void RemoveDecorateHandler(FunctionPointer<LoggerManager.OutputWriterDecorateHandler> func)

Parameters

Type	Name	Description
FunctionPointer<LoggerManager.OutputWriterDecorateHandler>	func	Function based decorator to remove

SetMinimalLogLevelForSink(int, LogLevel)

Changes the minimal level of the sink

Declaration

public void SetMinimalLogLevelForSink(int sinkId, LogLevel minimalLevel)

Parameters

Type	Name	Description
int	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.