Class ThreadSafeCollection<T>

Represents a thread-safe collection of objects that can be accessed by multiple threads concurrently.

Inheritance

object

ThreadSafeCollection<T>

Implements

IEnumerable<T>

IEnumerable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Coree.NETStandard.Classes.ThreadSafeCollection

Assembly: Coree.NETStandard.dll

Syntax

public class ThreadSafeCollection<T> : IEnumerable<T>, IEnumerable

Type Parameters

Name	Description
T	The type of elements in the collection. This type can be a class, including nullable reference types.

Remarks

This collection uses locking to ensure that its operations are thread-safe. The collection is implemented as a list where items can be added, removed, or retrieved in a manner that prevents race conditions and data corruption when accessed from multiple threads. Null values can be stored, depending on the type T.

Constructors

ThreadSafeCollection()

Initializes a new instance of the ThreadSafeCollection class that is empty.

Declaration

public ThreadSafeCollection()

Remarks

Creates an empty collection with no items. The collection is ready to be accessed by multiple threads using its thread-safe methods. It supports storing null values, if the type T permits.

Properties

Count

Gets the number of items in the collection, ensuring thread safety.

Declaration

public int Count { get; }

Property Value

Type	Description
int	The number of items currently in the collection. Access is synchronized to prevent race conditions.

HasItems

Gets a value indicating whether the collection has items, ensuring thread safety.

Declaration

public bool HasItems { get; }

Property Value

Type	Description
bool	true if the collection has items; otherwise, false.

Remarks

This property locks the collection to ensure that the check is performed in a thread-safe manner, preventing race conditions that could arise from concurrent modifications to the collection.

IsEmpty

Gets a value indicating whether the collection has no items, ensuring thread safety.

Declaration

public bool IsEmpty { get; }

Property Value

Type	Description
bool	true if the collection contains no items; otherwise, false.

Remarks

This property locks the collection to ensure that the check is performed in a thread-safe manner, preventing race conditions that could arise from concurrent modifications to the collection.

this[int]

Gets or sets the item at the specified index in a thread-safe manner.

Declaration

public T this[int index] { get; set; }

Parameters

Type	Name	Description
int	index	The zero-based index of the item to get or set.

Property Value

Type	Description
T	The item at the specified index.

Remarks

Access to the item is synchronized to ensure thread safety. Setting an item acquires a lock to prevent race conditions.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when the index is outside the bounds of the collection.

LastChangeAmount

Calculates the absolute change in count since the last update.

Declaration

public int LastChangeAmount { get; }

Property Value

Type	Description
int	The absolute change in the collection's size since the last modification.

Remarks

This property provides the absolute change in the collection's size since the last update, regardless of whether the size increased or decreased. It is useful for determining the magnitude of change without regard to the direction of that change. Access to this property is thread-safe.

LastChangeCount

Calculates the difference in the item count since the last update.

Declaration

public int LastChangeCount { get; }

Property Value

Type	Description
int	The net change in the collection's size since the last modification.

Remarks

This property provides the net change in the collection's count following the most recent operation, whether an addition or a removal. The value can be negative if the collection size has decreased since the last operation. Access to this value is thread-safe.

LastChangePercent

Calculates the percentage change in the count of items since the last update.

Declaration

public int LastChangePercent { get; }

Property Value

Type	Description
int	The percentage change in the collection size, always returned as a positive value to indicate the magnitude of change, or -1 if the change is undefined due to a zero previous count.

Remarks

This property returns the percentage change in the size of the collection based on the number of items before the last operation and the current number of items. If the previous count is zero, which means there were no items before the last operation, the change percentage is undefined, and thus returns -1. This helps in scenarios where a percentage change calculation would otherwise lead to a division by zero error.

LastModificationTime

Gets the time of the last modification to the collection.

Declaration

public DateTime LastModificationTime { get; }

Property Value

Type	Description
DateTime	The DateTime of the last update to the collection.

Remarks

This property records the timestamp when the last operation (addition, removal, or update) was performed on the collection. Access to this property is thread-safe, ensuring the timestamp is consistent with the last modification event.

ModificationTimeDifference

Gets the time difference between the last two modifications.

Declaration

public TimeSpan ModificationTimeDifference { get; }

Property Value

Type	Description
TimeSpan	The TimeSpan representing the duration between the last two updates.

Remarks

This property calculates the duration between the most recent and the previous modifications to the collection. It is useful for monitoring the time intervals between collection updates, which can be critical in performance-sensitive applications. Access to this property is thread-safe.

PeekCount

Gets the maximum number of items that have ever been in the collection.

Declaration

public int PeekCount { get; }

Property Value

Type	Description
int	The peak item count of the collection.

Remarks

This property reflects the highest count of items stored in the collection at any point in time. Access to this property is thread-safe, ensuring the count is accurate and consistent even when the collection is modified concurrently.

PreviousCount

Gets the count of items in the collection just before the most recent modification.

Declaration

public int PreviousCount { get; }

Property Value

Type	Description
int	The item count of the collection before the last modification.

Remarks

This property stores the number of items in the collection immediately before the last operation that added or removed items. It provides a snapshot of the collection's size prior to the last change, useful for understanding the state changes over time. Access to this property is thread-safe, ensuring that reads are consistent and not subject to partial updates.

PreviousModificationTime

Gets the time of the modification prior to the last modification.

Declaration

public DateTime PreviousModificationTime { get; }

Property Value

Type	Description
DateTime	The DateTime of the modification before the last update.

Remarks

This property records the timestamp of the modification that occurred just before the most recent one. It provides a historical reference for changes, useful for tracking the frequency or cadence of updates. Access to this property is thread-safe.

Methods

Add(T)

Adds an item to the collection in a thread-safe manner.

Declaration

public void Add(T item)

Parameters

Type	Name	Description
T	item	The item to be added to the collection. Can be null if the type T permits.

Remarks

Synchronizes access to the collection to safely add the item, supporting concurrent modifications.

AddRange(IEnumerable<T>)

Adds items to the collection in a thread-safe manner.

Declaration

public void AddRange(IEnumerable<T> items)

Parameters

Type	Name	Description
IEnumerable<T>	items	The items to be added to the collection. Can be null if the type T permits.

Remarks

Synchronizes access to the collection to safely add the item, supporting concurrent modifications.

Any(Func<T, bool>?)

Determines whether the collection contains any elements or any elements that match a predicate, if one is provided, in a thread-safe manner.

Declaration

public bool Any(Func<T, bool>? predicate = null)

Parameters

Type	Name	Description
Func<T, bool>	predicate	An optional predicate to test each element for a condition.

Returns

Type	Description
bool	true if the collection contains any elements or any elements that satisfy the condition; otherwise, false.

Remarks

This method locks the collection to ensure thread safety during the evaluation. If no predicate is provided, it simply checks if the collection has any elements.

Clear()

Removes all items from the collection in a thread-safe manner.

Declaration

public void Clear()

Remarks

This method locks the collection to ensure that no other operations can modify it concurrently during the clearing process.

Dequeue()

Removes and returns the item at the beginning of the collection in a thread-safe manner.

Declaration

public T Dequeue()

Returns

Type	Description
T	The item at the beginning of the collection if it exists; otherwise, throws an InvalidOperationException.

Remarks

This method locks the collection to ensure thread safety during the remove operation. It is part of the thread-safe queue functionality, providing a way to dequeue items (remove from the beginning). If the collection is empty, it throws an InvalidOperationException to enforce handling of the empty state condition by the caller.

Exceptions

Type	Condition
InvalidOperationException	Thrown when attempting to perform the Dequeue operation on an empty collection.

Enqueue(T)

Adds an item to the end of the collection in a thread-safe manner.

Declaration

public void Enqueue(T item)

Parameters

Type	Name	Description
T	item	The item to add to the collection. Can be null if the type T allows it.

Remarks

This method ensures that items can be added to the collection safely from multiple threads by synchronizing access. It functions as part of the thread-safe queue functionality, allowing items to be enqueued (added to the end).

GetCollectionCopyToList()

Creates and returns a deep copy of the entire collection as a List of T.

Declaration

public List<T> GetCollectionCopyToList()

Returns

Type	Description
List<T>	A new List containing deep copies of the items in the collection. Returns an empty list if the collection is empty.

Remarks

Locks the collection to ensure thread safety during the copy process. This method uses JSON serialization to create deep copies of the items, providing isolation from the original items. Modifications to the returned list or its items will not affect the original collection.

GetEnumerator()

Returns an enumerator that iterates through the collection in a thread-safe manner.

Declaration

public IEnumerator<T> GetEnumerator()

Returns

Type	Description
IEnumerator<T>	An IEnumerator<T> that can be used to iterate through the collection.

Remarks

This method creates a snapshot of the current state of the collection and returns an enumerator for this snapshot, allowing for safe iteration over the collection items even when other threads might be modifying the collection concurrently. Note that the snapshot is a shallow copy; thus, the enumeration reflects the collection's state at the moment of the snapshot's creation.

GetItemAt(int)

Retrieves the item at the specified index in a thread-safe manner.

Declaration

public T GetItemAt(int index)

Parameters

Type	Name	Description
int	index	The zero-based index of the item to retrieve.

Returns

Type	Description
T	The item at the specified index. Can be null if the item itself is null or if the type T allows null values.

Remarks

Accesses the collection in a synchronized context to ensure safe retrieval of the item.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when the specified index is outside the bounds of the collection.

GetItemCopyAt(int)

Returns a deep copy of the item at the specified index, ensuring thread safety and isolation from the original collection.

Declaration

public T? GetItemCopyAt(int index)

Parameters

Type	Name	Description
int	index	The zero-based index of the item to copy.

Returns

Type	Description
T	A deep copy of the item at the specified index. Returns null if the original item is null.

Remarks

This method locks the collection during the operation and uses JSON serialization to create a deep copy of the item, ensuring that modifications to the returned object do not affect the original item in the collection. Throws ArgumentOutOfRangeException if the index is out of the valid range.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when the index is out of range.

Peek()

Returns the last item from the collection without removing it, in a thread-safe manner.

Declaration

public T Peek()

Returns

Type	Description
T	The last item of the collection if it exists; otherwise, throws an InvalidOperationException.

Remarks

This method locks the collection to ensure thread safety during the retrieval operation. If the collection is empty, it throws an InvalidOperationException to notify the caller of the empty state, aligning with the behavior of Pop.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the collection is empty.

Pop()

Removes and returns the last item from the collection in a thread-safe manner.

Declaration

public T Pop()

Returns

Type	Description
T	The last item of the collection if it exists; otherwise, throws an InvalidOperationException.

Remarks

This method locks the collection to ensure thread safety during the remove operation. If the collection is empty, it throws an InvalidOperationException. This change ensures that the caller is explicitly aware of the empty state.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the collection is empty.

Push(T)

Adds an item to the collection in a thread-safe manner.

Declaration

public void Push(T item)

Parameters

Type	Name	Description
T	item	The item to add to the collection. Can be null for nullable reference types.

Remarks

This method ensures that the collection can be safely modified from multiple threads by synchronizing access. The item is added to the end of the collection. It accepts null values for types that allow it.

Remove(T)

Removes the first occurrence of a specific item from the collection in a thread-safe manner.

Declaration

public void Remove(T item)

Parameters

Type	Name	Description
T	item	The item to remove from the collection. Can be null if the type T permits.

Remarks

Synchronizes access to the collection to safely remove the item, supporting concurrent modifications. If the item is not found, no action is taken.

RemoveAll(Func<T, bool>)

Removes all items from the collection that match the specified predicate in a thread-safe manner.

Declaration

public void RemoveAll(Func<T, bool> predicate)

Parameters

Type	Name	Description
Func<T, bool>	predicate	A delegate that defines the conditions of the elements to remove from the collection.

Remarks

This method locks the collection to ensure that no other operations modify it concurrently while it is being updated. It's particularly useful for batch removal of items based on specific conditions. The actual removal is performed efficiently in a single pass through the collection.

RemoveAt(int)

Removes the item at the specified index from the collection in a thread-safe manner.

Declaration

public void RemoveAt(int index)

Parameters

Type	Name	Description
int	index	The zero-based index of the item to remove.

Remarks

This method locks the collection to ensure exclusive access during the removal operation. It captures the state before the change and updates internal timestamps to reflect the modification time. An ArgumentOutOfRangeException is thrown if the index is outside the valid range of the collection's indices. This method updates the previous and last modification times to track changes.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if the index is less than 0 or equal to or greater than the number of items in the collection.

TakeAll(Func<T, bool>)

Finds and removes all items matching the given predicate from the collection in a thread-safe manner.

Declaration

public IEnumerable<T> TakeAll(Func<T, bool> predicate)

Parameters

Type	Name	Description
Func<T, bool>	predicate	The predicate used to find the items to remove.

Returns

Type	Description
IEnumerable<T>	An enumerable of all items that were removed from the collection.

Remarks

Synchronizes access to the collection to safely remove the items, supporting concurrent modifications. Returns an empty enumerable if no items match the predicate.

TakeAt(int)

Gets and removes the item at the specified index from the collection in a thread-safe manner.

Declaration

public T TakeAt(int index)

Parameters

Type	Name	Description
int	index	The zero-based index of the item to fetch and remove.

Returns

Type	Description
T	The item that was removed from the collection.

Remarks

Synchronizes access to the collection to safely remove the item, supporting concurrent modifications. If the index is out of range, an ArgumentOutOfRangeException is thrown.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when the index is out of range.

TakeFirst(Func<T, bool>)

Finds and removes the first item matching the given predicate from the collection in a thread-safe manner.

Declaration

public T? TakeFirst(Func<T, bool> predicate)

Parameters

Type	Name	Description
Func<T, bool>	predicate	The predicate used to find the item to remove.

Returns

Type	Description
T	The item that was removed from the collection, or null if no item matched the predicate.

Remarks

Synchronizes access to the collection to safely remove the item, supporting concurrent modifications. If no item matches the predicate, null is returned.

ThreadSafeTransform()

Provides a thread-safe snapshot of the collection, allowing for safe read access by other operations without risk of modification during enumeration.

Declaration

public IEnumerable<T> ThreadSafeTransform()

Returns

Type	Description
IEnumerable<T>	A snapshot of the collection as a new list, ensuring that the original collection remains untouched during access.

Remarks

This method locks the collection to prevent other operations from modifying it while the snapshot is being created, ensuring consistent data state.

Examples

var itemsSnapshot = myCollection.ThreadSafeTransform();
foreach (var item in itemsSnapshot) {
    Console.WriteLine(item);
}

ThreadSafeTransformDeepClone<TResult>(Func<IEnumerable<T>, IEnumerable<TResult>>)

Performs a LINQ operation on a snapshot of the collection and returns a deep copy of the results in a thread-safe manner.

Declaration

public IEnumerable<TResult> ThreadSafeTransformDeepClone<TResult>(Func<IEnumerable<T>, IEnumerable<TResult>> operation)

Parameters

Type	Name	Description
Func<IEnumerable<T>, IEnumerable<TResult>>	operation	A function representing the LINQ operation to be performed on the collection.

Returns

Type	Description
IEnumerable<TResult>	An IEnumerable<T> that contains a deep copy of the result of applying the LINQ operation on the collection snapshot.

Type Parameters

Name	Description
TResult	The type of the result elements.

Remarks

Similar to ThreadSafeTransform(), this method locks the collection and operates on a snapshot to ensure thread safety. After performing the specified LINQ operation, it creates a deep copy of the result using JSON serialization. This approach guarantees that the operation's results are completely isolated from the original items in the collection, providing additional safety against mutations.

ThreadSafeTransform<TResult>(Func<IEnumerable<T>, IEnumerable<TResult>>)

Performs a LINQ operation on a snapshot of the collection in a thread-safe manner.

Declaration

public IEnumerable<TResult> ThreadSafeTransform<TResult>(Func<IEnumerable<T>, IEnumerable<TResult>> operation)

Parameters

Type	Name	Description
Func<IEnumerable<T>, IEnumerable<TResult>>	operation	A function representing the LINQ operation to be performed on the collection.

Returns

Type	Description
IEnumerable<TResult>	An IEnumerable<T> that contains the result of applying the LINQ operation on the collection snapshot.

Type Parameters

Name	Description
TResult	The type of the result elements.

Remarks

This method locks the collection, takes a snapshot, and then applies the specified LINQ operation. It ensures thread safety by preventing other operations from modifying the collection during execution. The operation is performed on a snapshot to avoid locking during the entire enumeration, but it means the operation does not reflect changes made to the collection after the snapshot is taken.

Implements

IEnumerable<T>

IEnumerable

Extension Methods

CriteriaEnumerableExtensions.ApplyCriteria<T>(IEnumerable<T>, CriteriaItems)

CriteriaEnumerableExtensions.ApplyCriteria<T, TValue>(IEnumerable<T>, CriteriaItem<TValue>)