Struct DispatchQueue

Double buffered thread-safe queue
Limited by a maximum size that is passed in the constructor. This is an important for performance, to avoid memory reallocation during the work.

In the usual case the queue works in the asynchronous mode:

One buffer is used for write: several threads can add new LogMessage's to it, no one can read from that buffer. That is done via Enqueue(PayloadHandle, long, LogLevel) method that does that under the read lock[1].
Second buffer is used as a read-only buffer: several sinks can read from it, without modifying anything. This is done via BeginRead() and EndRead() that enters/exits the read lock[1].
Second buffer also can be in an exclusive mode: Cleanup system calls BeginReadExclusive() to enter the exclusive lock[2] to make sure only it can access the read buffer at the time to release the memory used by the messages. EndReadExclusiveClearAndFlip() at the end of its work, cleaning the read buffer and flipping write/read ones, so now the write buffer is empty. Exclusive lock is unlocked after this.
Sort() of the second (read) buffer is done under an exclusive lock[2], since it modifies the list, so it is not safe to read it.

Another use case that is much slower - synchronous access. LockAndSortForSyncAccess(out UnsafeList<LogMessage>, out UnsafeList<LogMessage>) will put the queue under the exclusive lock[2] and return both buffers for read-write access.
When the access is finished EndLockAfterSyncAccess() call will clear both buffers and unlock the data structure.
This is used in the case when full synchronous flush is needed.

Lock is used to control the thread-safe access for this data structure:
[1] Read-lock allows several threads to take it, but only if no exclusive lock is taken. Guarantees that no exclusive lock [2] will be taken during it. Read-lock is used in situations when it is ok for multiple threads to do some kind of access, like: add new elements (see Enqueue(PayloadHandle, long, LogLevel)), read simultaneously without modifications (see BeginRead(), EndRead()).
[2] Exclusive lock is used when only one thread can enter and no read-locks are taken. This lock is used to cleanup the memory of the messages (see BeginReadExclusive()) and then clear the read and swap the read and write buffers (see EndReadExclusiveClearAndFlip()).

Note: While read buffer is in read-only BeginRead() -- EndRead() mode the write buffer still can be used to Enqueue(PayloadHandle, long, LogLevel) from multiple threads

Implements

IDisposable

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

[BurstCompile]
public struct DispatchQueue : IDisposable

Constructors

DispatchQueue(int)

Constructor for DispatchQueue.

Declaration

public DispatchQueue(int size)

Parameters

Type	Name	Description
int	size	Maximum length of the queue

Remarks

Creates two lists with the maximum amount of LogMessage's that it can process before it should be flipped.

Properties

IsCreated

Is true if this struct was initialized.

Declaration

public bool IsCreated { get; }

Property Value

Type	Description
bool

TotalLength

Total length of read-only and write buffers. Usually used for testing of internal state of the queue.

Declaration

public int TotalLength { get; }

Property Value

Type	Description
int

Methods

BeginRead()

Puts DispatchQueue into reading lock mode till EndRead() is called to prevent buffer flipping. Several threads can use this at the same time for reading only.

Declaration

public UnsafeList<LogMessage>.ParallelReader BeginRead()

Returns

Type	Description
UnsafeList<LogMessage>.ParallelReader	ParallelReader is returned that can be used to get all the LogMessage's from the read buffer

BeginReadExclusive()

Puts DispatchQueue into exclusive lock mode till EndReadExclusiveClearAndFlip() is called to prevent buffer flipping. Only one thread can access the read buffer, usually to modify it (cleanup system can free the memory that is used by messages).

Declaration

public UnsafeList<LogMessage>.ParallelReader BeginReadExclusive()

Returns

Type	Description
UnsafeList<LogMessage>.ParallelReader	ParallelReader is returned that can be used to get all the LogMessage's from read buffer, usually to dispose them

Dispose()

Dispose call that will call Dispose for the lists (under lock) if IsCreated is true. IDisposable

Declaration

public void Dispose()

EndLockAfterSyncAccess()

Unlocks DispatchQueue exclusive lock that was initiated by LockAndSortForSyncAccess(out UnsafeList<LogMessage>, out UnsafeList<LogMessage>) and clears all the buffers.

Declaration

public void EndLockAfterSyncAccess()

EndRead()

Unlocks DispatchQueue reading lock that was initiated by BeginRead()

Declaration

public void EndRead()

EndReadExclusiveClearAndFlip()

Unlocks DispatchQueue exclusive lock that was initiated by BeginReadExclusive(), clears the read buffer and swaps the buffers, so now the write buffer is empty.

Declaration

public void EndReadExclusiveClearAndFlip()

Enqueue(PayloadHandle, long, LogLevel)

Adds new message to the write buffer under read lock. Gets the timestamp just before adding the message to the queue.

Declaration

public void Enqueue(PayloadHandle payload, long stacktraceId, LogLevel logLevel)

Parameters

Type	Name	Description
PayloadHandle	payload	PayloadHandle of the log message
long	stacktraceId	Stacktrace id of the log message or 0 if none
LogLevel	logLevel	LogLevel of the log message

LockAndSortForSyncAccess(out UnsafeList<LogMessage>, out UnsafeList<LogMessage>)

Enters the exclusive lock for DispatchQueue to get the access for both buffers till EndLockAfterSyncAccess() is called.

Declaration

public void LockAndSortForSyncAccess(out UnsafeList<LogMessage> olderMessages, out UnsafeList<LogMessage> newerMessages)

Parameters

Type	Name	Description
UnsafeList<LogMessage>	olderMessages	Returns the buffer with older messages (read buffer)
UnsafeList<LogMessage>	newerMessages	Returns the buffer with newer messages (write buffer)

Implements

IDisposable