Library Setup and Driver Paths

class fluxEngine.Handle(licenseData)

fluxEngine Handle

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

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

Important: this has the consequence that if a new handle is to be created, the old handle has to be properly deleted, via the del keyword.

Each handle is associated with a number of processing threads that the user can manage. A handle may only be used to process a single model at the same time, though multiple models may be loaded for a given handle.

Valid license data must be passed to the constructor, 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.

If an error occurs (for example because the license was not valid), an exception will be thrown.

Parameters

licenseData (binary) – The raw bytes of the license file

createProcessingThreads(count, initFunction=None)

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 count 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 count.

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.

If initFunction is not None it will be called at the beginning of every newly created background thread. This allows the user to customize the thread properties (such as the CPU affinity) themselves.

This method will only return once all threads have been created and their initialization functions (if specified) have run.

The thread initialization functions are only called for the background threads that are started by this method; this means that for a count of 4 the initialization function will be called in three 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 could be something like this:

def init_thread(threadId, threadCount):
    print("Creating thread {0} of {1}".format(threadId, threadCount))
handle.createProcessingThreads(4, init_thread)

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.

If an error occurs, an exception will be thrown.

Parameters

  • count (int) – 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)

  • initFunction (callable) – The thread initialization function, or None if no special thread initialization is to be used

processingPluginCount()

Get 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.

Returns

The number of processing plugins that were loaded

Return type

int

processingPluginId(index)

Get the id of a processing plugin

For a given processing plugin identified by the index parameter, 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 that is encoded as a string.

Parameters

index (int) – 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.

Returns

The id of the processing plugin

Return type

str

processingPluginIndexById(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 error will be raised.

Parameters

id (str) – The id of the plugin, must be parseable as a UUID.

Returns

The index of the plugin, which may be used to address the plugin using the other plugin related methods.

Return type

int

processingPluginIsAvailable(index)

Check if a processing plugin is available

For a given processing plugin identified by the index parameter, 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.

Parameters

index (int) – 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.

Returns

Whether the processing plugin is available.

Return type

str

processingPluginIsEnabled(index)

Check if a processing plugin is enabled

For a given processing plugin identified by the index parameter, 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 not 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.

Parameters

index (int) – 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.

Returns

Whether the processing plugin is enabled.

Return type

str

processingPluginName(index)

Get the name of a processing plugin

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

Parameters

index (int) – 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.

Returns

The name of the processing plugin

Return type

str

processingPluginSetEnabled(index, enabled)

Enable or disable a processing plugin

For a given processing plugin identified by the index parameter, 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.)

Parameters

  • index (int) – 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.

  • enabled (bool) – Whether the processing plugin should be enabled or not

setDriverBaseDirectory(path)

Set the driver base directory

When loading drivers this sets the base directory where the device drivers may be found. If this method is not called, or an empty value or None is passed, a default will be used that is non sensible for the use in a Python context, so the user should call this when intending to use fluxEngine in combination with drivers..

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

setDriverIsolationExecutable(path)

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.

By default the driver isolation executable will be searched for in the directory of the Python module itself.

stopProcessingThreads()

Stop all existing processing threads.

This will stop any background threads that are currently associated with the default processing queue set of a given handle. If processing is currently active on the default processing queue set of 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 with the default processing queue set of the handle 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.

Processing Queue Sets

class fluxEngine.ProcessingQueueSet(handle)

fluxEngine Processing Queue Set

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

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.

Parameters

handle (Handle) – The handle to create the processing queue set for

createProcessingThreads(count, initFunction=None)

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 count 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 count.

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 that was created for this processing queue set before a call to this method was made is marked as invalid and can only be destroyed, but not used anymore.

If initFunction is not None it will be called at the beginning of every newly created background thread. This allows the user to customize the thread properties (such as the CPU affinity) themselves.

This method will only return once all threads have been created and their initialization functions (if specified) have run.

The thread initialization functions are only called for the background threads that are started by this method; this means that for a count of 4 the initialization function will be called in three 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 could be something like this:

def init_thread(threadId, threadCount):
    print("Creating thread {0} of {1}".format(threadId, threadCount))
processingQueueSet.createProcessingThreads(4, init_thread)

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.

If an error occurs, an exception will be thrown.

Parameters

  • count (int) – 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)

  • initFunction (callable) – The thread initialization function, or None if no special thread initialization is to be used

stopProcessingThreads()

Stop all existing processing threads.

This will stop any background threads that are currently associated with a given processing queue set. If processing is currently active on the processing queue set, 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 for this processing queue set 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.