ILNumerics Threading Model

ILNumerics is thread safe since version 7.0.163. This document lines out certain guarantees this claim brings.

Threading Guarantees

• Numeric arrays in ILNumerics Computing Engine are thread safe. They can be used for reading and for writing from multiple threads concurrently with the guarantee to remain integrity.
  • By 'use' we mean: calls to any public instance or extension method on an array A, to provide A as an argument to any static function of ILNumerics.ILMath or ILNumerics.numpy while access to A is shared by multiple threads.
  • 'Integrity' means: the invocation of instance methods of A and the processing of any public static function of the ILMath / numpy classes will complete normally, regardless if A is in use by other threads concurrently. 
• Without proper sychronization in user code the following guarantees are provided:
  • Methods reading from an array (instance and extension methods, static methods of ILMath / numpy): during the methods processing the array will be held alive. Concurrent writes to the same array instance may change the element values, though. However, the array will remain 'intact': at any time a reader will observe an internal state which allows to read the size and all element values according to the size. The overall configuration of the array is correct and corresponds to the state of the array at the moment the observation happened. Reading from arrays is always allowed and works lock-free ('multiple reader').
  • Methods writing to an array: mutable instance variables (numeric Array<T>, numeric OutArray<T>, Logical, OutLogical) can be shared and concurrently be written and read to. For such concurrent access is true: when two or more threads attempt to write to the same array the array will remain intact, no data is lost. The order of writes is undefined. Thus, if the writes attempt to change the same region of the array (the same element values) the result is undefined. Writes are subject to locking, hence concurrent writes are serialized.

General Recommendations & Limitations

• Without manual synchronization a reader of a shared array instance may "see" partial data from concurrent writes. However, no crippled or invalid values will be observed due to concurrent writes. 
• Concurrent writes causing the array size to change (Matlab^(R) or ILNumericsV4 array style) are allowed. Hoewever, since the order of such writes is undefined so is the outcome: the array may or may not be shrunk or expanded. Subsequent writes must take this into account. Either, partial writes (via indexing or SetRange) must be prepared for the changed array size. Or, (recommended) pre-allocate all arrays with the maximum size required throughout their lifetime and prevent them from expanding or shrinking.
• The result of sharing data in regions of accelerated code and/or accessing cell arrays from multiple threads concurrently is undefined. The same is true for shared access to instances of Cell, InCell and OutCell.