Library Setup and Driver Paths

Handle

class LuxFlux.fluxEngineNET.Handle : IDisposable 

fluxEngine Handle

This class represents a handle to fluxEngine’s functionality. It is required to perform any operation with fluxEngine.

The default constructor does not actually create an object, the user must use one of the other constructors to actually create and initialize a handle.

Currently only one initialized handle may be created at a time. (This restriction will be relaxed in a future version.)

Each handle is associated with a default processing queue set so that the user need not create a processing queue set themselves. If processing multiple models at the same time is required, the user must create processing queue sets.

When destroying a handle, to ensure that the underlying fluxEngine handle is actually destroyed (in case at a later point in time a new handle is to be created), please use the Collect() method of the GC class:

handle = null; GC.Collect();

Public Functions

Handle (byte[] licenseData)

Initialize fluxEngine

This constructor initializes fluxEngine. Valid license data must be passed to this function, otherwise fluxEngine will not initialize itself. It is up to the user to read the license data from the given license file, if they choose to store it in a file.

The following example shows the typical usage if the license is stored in a file:

byte[] licenseData = System.IO.File.ReadAllBytes(@"C:\fluxEngine.lic");
fluxEngineNET.Handle handle = new fluxEngineNET.Handle(licenseData);

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws LicenseError:

void CreateProcessingThreads (int threadCount)

Create processing threads

fluxEngine may use parallization to speed up processing. In order to achieve this background threads must be created to run on additional CPU cores.

Calling this method is optional: by default processing will be single-threaded.

This method will start count - 1 threads when called, as the thread that asks for processing is always considered to be the first thread (with id 0). For example, if 4 is supplied to threadCount this function will start 3 threads that run in the background. The thread that the user uses to call ProcessingContext.ProcessNext() will be considered the thread with id 0, making processing use a total of 4 threads, which is the value supplied for threadCount .

This method may only be called if there are currently no background threads associated with this handle. Otherwise StopProcessingThreads() must be called first to change the number of threads.

Any processing context that was created before a call to this method was made is marked as invalid and can only be destroyed, but not used anymore.

Param threadCount:: The number of threads to use for parallel processing (one less than this number will be created by this method, see the description for details)
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws InitializationError:

void CreateProcessingThreads (int threadCount, Action<int, int> initFunction)

Create processing threads (extended version)

Please read the documentation of the primary overload of createProcessingThreads() for a general overview.

This extended method allows the user to supply a thread initialization function that will be called at the beginning of the newly created background threads. This allows the user to customize the thread properties (such as the thread priority or the CPU affinity) themselves.

This function will only return once all thread initialization functions have run.

The thread initialization functions are only called for the backgronud threads that are started by this method; this means that for a threadCount of 4 the initialization function will be called in 3 background threads, and it is up to the user to alter the thread in which they call ProcessingContext.ProcessNext() to process data with fluxEngine.

The threads will be created sequentially, the next thread being created only after the previous thread’s initialization function has completed. This allows the user to directly modify global data structures in the initialization functions without the need for locking.

An example call to this method would be something like this:

handle.CreateProcessingThreads(4, (int threadId, int threadCount) =>
{
    int cpuCoreId = threadId;
    PinCurrentThreadCPUCoreWithId(cpuCoreId);
    SetCurrentThreadPriority(High);
    // Thread 0 will be thre thread that calls processNext()
    // on a processing context, and will have to have these
    // settings applied elsewhere
});

(The functions called within the initialization function are just example names. It would be up to the user to implement them.)

If the user detects an error condition during thread initialization and wants to abort, they should throw an exception in the initialization function they supplied, which will be propagated out of the call to this method.

Important: any attempt to call a method that accesses this handle inside the initialization functions will create a deadlock.

This method may only be called if there are currently no background threads associated with this handle. Otherwise StopProcessingThreads() must be called first to change the number of threads.

Any processing context that was created before a call to this method was made is marked as invalid and can only be destroyed, but not used anymore.

Param threadCount:: The number of threads to use for parallel processing (one less than this number will be created by this method, see the description for details)
Param initFunction:: The thread initialization function
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws InitializationError:

void StopProcessingThreads ()

Stop all existing processing threads

This will stop any background threads that are currently associated with a given handle. If processing is currently active on the handle, it will be aborted, as if ProcessingContext.Abort() had been called. In that case this method may take a bit of time, as abort operations are not immediate, and this method will wait until the abort has completed.

Any processing context that was created before a call to this method was made is marked as invalid and can only be destroyed, but not used anymore.

This method is always successful: the only errors that could occur when calling this method would be non-recoverable.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:

void SetDriverBaseDirectory (string directory)

Set the driver base directory

When loading drivers this sets the base directory where the drivers may be found. If this method is not called, or an empty value is passed, the directory drivers one level above the directory of the currently running executable will be used. For example, if the executable is , the default drivers directory would be . (This is the case on all platforms.)

Note that if this method is not used the user can also override the default via an environment variable per driver type. (See the introductory documentation for more details.)

The directory specified here must exist, otherwise it will not be used and an error will be raised.

Param directory:: The driver base directory
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:

void SetDriverIsolationExecutable (string executable)

Set the path to the driver isolation executable

Drivers are loaded via the fluxDriverIsolation executable (on Windows fluxDriverIsolation.exe), in case the default is not where the executable is deployed. The defaults are:

On Windows and macOS the fluxDriverIsolation executable is assumed to be in the same directory as the current executable by default. For example, if the executable is on Windows, the default driver isolation path is assumed to be . Similarly, on macOS, if the main executable is in /Applications/engine_test.app/Contents/MacOS/engine_test, the driver isolation executable is assumed to be in /Applications/engine_test.app/Contents/MacOS/fluxDriverIsolation.

On all other platforms (Linux) the executable is assumed to be in ../libexec/fluxDriverIsolation relative to the current executable path. For example, if the executable is in /opt/engine_test/bin/engine_test, the driver isolation executable will be looked for in /opt/engine_test/libexec/fluxDriverIsolation by default.

Param executable:: The path to the fluxDriverIsolation executable
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:

Guid ProcessingPluginId (int index)

Get the id of a processing plugin

For a given processing plugin identified by index , which must run from 0 to one less than the count returned by ProcessingPluginCount, return the id of that plugin.

The id will be a UUID.

Param index:: The index of the plugin, must be between 0 and one less than the total number of plugins. The index will remain stable for the lifetime of the fluxEngine handle
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Return:: The id of the processing plugin

string ProcessingPluginName (int index)

Get the name of a processing plugin

For a given processing plugin identified by index , which must run from 0 to one less than the count returned by ProcessingPluginCount, return a human-readable name of that plugin.

Param index:: The index of the plugin, must be between 0 and one less than the total number of plugins. The index will remain stable for the lifetime of the fluxEngine handle
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Return:: The name of the processing plugin

bool ProcessingPluginIsAvailable (int index)

Check if a processing plugin is available

For a given processing plugin identified by index , which must run from 0 to one less than the count returned by ProcessingPluginCount, determine if the plugin is available on this system.

A plugin may not be available on the current system due to an incompatibility. For example, a plugin that provides an AVX2 implementation will not be available on a CPU that doesn’t support AVX2, or on an operating system that doesn’t support it, even if the CPU does.

Param index:: The index of the plugin, must be between 0 and one less than the total number of plugins. The index will remain stable for the lifetime of the fluxEngine handle
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Return:: Whether the processing plugin is available

bool ProcessingPluginIsEnabled (int index)

Check if a processing plugin is enabled

For a given processing plugin identified by index , which must run from 0 to one less than the count returned by ProcessingPluginCount, determine if the plugin is currently enabled.

All plugins are enabled by default, but if a plugin is available (e.g. a plugin that provides an AVX2 implementation is not available on a CPU that doesn’t support AVX2), the fact that the plugin is enabled will have no effect. See ProcessingPluginIsAvailable to check if a plugin is available.

Plugins are only disabled if they are explicitly disabled by the user.

Param index:: The index of the plugin, must be between 0 and one less than the total number of plugins. The index will remain stable for the lifetime of the fluxEngine handle
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Return:: Whether the processing plugin is enabled

void ProcessingPluginSetEnabled (int index, bool enabled)

Enable or disable a processing plugin

For a given processing plugin identified by index , which must run from 0 to one less than the count returned by ProcessingPluginCount, enable or disable it.

All plugins are enabled by default, but if a plugin is available (e.g. a plugin that provides an AVX2 implementation is not available on a CPU that doesn’t support AVX2), the fact that the plugin is enabled will have no effect. See ProcessingPluginIsAvailable to check if a plugin is available.

Plugins are only disabled if they are explicitly disabled by the user by this method.

If processing contexts have already been created a call to this function will have no effect on the already existing contexts, it will only affect newly created contexts. (The old contexts will still work though.)

Param index:: The index of the plugin, must be between 0 and one less than the total number of plugins. The index will remain stable for the lifetime of the fluxEngine handle
Param enabled:: Whether the plugin should be enabled
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:

int ProcessingPluginIndexById (Guid id)

Find a processing plugin based on its id

Attempt to determine the index of a processing plugin that has a specific id that was specified by the user.

If the plugin could not be found, an exception will be thrown.

Param id:: The id of the plugin
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Return:: The index of the plugin, which may be used to address the plugin using the other plugin related methods.

void Dispose ()

Dispose of this object

This will free all resources associated with this object. The object should not be used anymore after a call to this method.

Properties

int ProcessingPluginCount { get; set; }

The number of processing plugins that were loaded by fluxEngine

During startup fluxEngine will automatically load any processing plugin it can find in a path adjacent to where the fluxEngine DLLs are installed. Any plugin that is found is attempted to be loaded.

Plugins may provide additional functionality to fluxEngine, or they may provide implementations of algorithms that are optimized for specific devices, for example specific CPU instruction sets.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:

ProcessingQueueSet

class LuxFlux.fluxEngineNET.ProcessingQueueSet : IDisposable 

fluxEngine Processing Queue Set

This class represents a processing queue set. A processing queue set is used for processing queues.

The default constructor does not actually create an object, the user must use one of the other constructors to actually create and initialize a processing queue set.

Each processing queue set is associated with a number of processing threads that the user can manage. A processing queue set may only be used to process a single model at the same time, but multiple processing queue sets may be created.

Public Functions

ProcessingQueueSet (Handle handle)

Create a new processing queue set for a given handle

Param handle:: The handle to create the processing queue set for
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:

void CreateProcessingThreads (int threadCount)

Create processing threads

fluxEngine may use parallization to speed up processing. In order to achieve this background threads must be created to run on additional CPU cores.

Calling this method is optional: by default processing will be single-threaded.

This method will start threadCount - 1 threads when called, as the thread that asks for processing is always considered to be the first thread (with id 0). For example, if 4 is supplied to threadCount this function will start 3 threads that run in the background. The thread that the user uses to call ProcessingContext.ProcessNext will be considered the thread with id 0, making processing use a total of 4 threads, which is the value supplied for threadCount .

This method may only be called if there are currently no background threads associated with this processing queue set. Otherwise StopProcessingThreads must be called first to change the number of threads.

Any processing context associated with this processing queue set that was created before a call to this method was made is marked as invalid and can only be destroyed, but not used anymore.

Param threadCount:: The number of threads to use for parallel processing (one less than this number will be created by this method, see the description for details)
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws InitializationError:

void CreateProcessingThreads (int threadCount, Action<int, int> initFunction)

Create processing threads (extended version)

Please read the documentation of the primary overload of CreateProcessingThreads() for a general overview.

This extended method allows the user to supply a thread initialization function that will be called at the beginning of the newly created background threads. This allows the user to customize the thread properties (such as the thread priority or the CPU affinity) themselves.

This function will only return once all thread initialization functions have run.

The thread initialization functions are only called for the backgronud threads that are started by this method; this means that for a threadCount of 4 the initialization function will be called in 3 background threads, and it is up to the user to alter the thread in which they call ProcessingContext.ProcessNext() to process data with fluxEngine.

The threads will be created sequentially, the next thread being created only after the previous thread’s initialization function has completed. This allows the user to directly modify global data structures in the initialization functions without the need for locking.

An example call to this method would be something like this:

queueSet.CreateProcessingThreads(4, (int threadId, int threadCount) =>
{
    int cpuCoreId = threadId;
    PinCurrentThreadCPUCoreWithId(cpuCoreId);
    SetCurrentThreadPriority(High);
    // Thread 0 will be thre thread that calls processNext()
    // on a processing context, and will have to have these
    // settings applied elsewhere
});

(The functions called within the initialization function are just example names. It would be up to the user to implement them.)

If the user detects an error condition during thread initialization and wants to abort, they should throw an exception in the initialization function they supplied, which will be propagated out of the call to this method.

Important: any attempt to call a method that accesses this processing queue set inside the initialization functions will create a deadlock.

This method may only be called if there are currently no background threads associated with this handle. Otherwise StopProcessingThreads() must be called first to change the number of threads.

Any processing context associated with this processing queue set that was created before a call to this method was made is marked as invalid and can only be destroyed, but not used anymore.

Param threadCount:: The number of threads to use for parallel processing (one less than this number will be created by this method, see the description for details)
Param initFunction:: The thread initialization function
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws InitializationError:

void StopProcessingThreads ()

Stop all existing processing threads

This will stop any background threads that are currently associated with a given handle. If processing is currently active on the handle, it will be aborted, as if ProcessingContext.Abort() had been called. In that case this method may take a bit of time, as abort operations are not immediate, and this method will wait until the abort has completed.

Any processing context that was created before a call to this method was made is marked as invalid and can only be destroyed, but not used anymore.

This method is always successful: the only errors that could occur when calling this method would be non-recoverable.

void Dispose ()

Dispose of this object

This will free all resources associated with this object. The object should not be used anymore after a call to this method.