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
Inherited Members
Namespace: Unity.Logging
Assembly: solution.dll
Syntax
[BurstCompile]
public struct DispatchQueue : IDisposable

Constructors

Name Description
DispatchQueue(int)

Constructor for DispatchQueue.

Properties

Name Description
IsCreated

Is true if this struct was initialized.
TotalLength

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

Methods

Name Description
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.
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).
Dispose()

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

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

Unlocks DispatchQueue reading lock that was initiated by BeginRead()
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.
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.
LockAndSortForSyncAccess(out UnsafeList<LogMessage>, out UnsafeList<LogMessage>)

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