Library Setup and Driver Paths

class fluxEngine::Handle

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

Library Setup

Handle() = default

Default constructor.

This does not actually create a handle, but allows the user to create variables that can be used to move a handle around.

inline Handle(void const *licenseData, std::size_t licenseDataSize)

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.

If the call is successful a handle will be created. The following example shows a typical usage: 

{
    fluxEngine::Handle handle(licenseData, licenseDataSize);
    // do something with handle
}
// handle has fallen out of scope and is destroyed

The resulting handle has move semantics, see the following example: 

fluxEngine::Handle handle(licenseData, licenseDataSize);
// do some initial things
someObject.setHandle(std::move(handle));

If an error occurs (for example, because the license was not valid), an exception will be thrown. The following exceptions may be thrown by this constructor:

Parameters

  • licenseData: The raw bytes of the license

  • licenseDataSize: The number of raw bytes of the license

inline Handle(std::vector<std::byte> const &licenseData)

Initialize fluxEngine (convenience wrapper)

If the license data is present as a std::vector<std::byte> this convenience wrapper exists to allow the user to use that to construct a fluxEngine handle.

This wrapper is only available when compiling with a compiler that supports C++17.

See the documentation for the primary constructor for more details.

Parameters

  • licenseData: The raw bytes of the license

inline Handle(Handle &&other) noexcept

Move constructor.

Parameters

  • other: The handle to move into the newly created object

inline Handle &operator=(Handle &&other) noexcept

Move assignment operator.

Return

A reference to this object

Parameters

  • other: The handle to move into this object

inline ~Handle()

Destructor.

Destroy a library handle, freeing its resources. All background threads will be stopped in the same manner as if stopProcessingThreads() had been called.

Any processing context associated with this handle will be marked as invalid and may hence not be used anymore. However, some memory associated with remaining processing contexts that have not been freed previous to a call to this method may still be in use until each remaining processing context is freed by the user.

inline void createProcessingThreads(int count)

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 an error occurs, an exception will be thrown. The following exceptions may be thrown by this method:

Parameters

  • count: 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)

template<typename T>
inline void createProcessingThreads(int count, T &&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 count 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 could be something like this: 

handle.createProcessingThreads(4, [&] (int threadId, int threadCount) {
    (void) threadCount;
    // Run thread 1 on core 1, thread 2 on core 2, etc.
    int cpuCoreId = threadId;
    pinCurrentThreadCPUCoreWithId(cpuCoreId);
    setCurrentThreadPriority(ThreadPriority::High);
    // The thread 0 will be the 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.

If an error occurs, an exception will be thrown. The following exceptions may be thrown by this method:

Parameters

  • count: 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: The thread initialization function. This may be a lambda function

inline void stopProcessingThreads() noexcept

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.

This method may safely be called on an invalid handle, that would have no effect.

inline explicit operator bool() const noexcept

Boolean conversion operator.

This allows the user to easily check if a variable of this type currently holds a valid handle. For example: 

if (handle) {
    // the handle is valid
}

Driver Paths

These methods of the Handle class allow the user to customize the paths for the driver framework.

inline void setDriverBaseDirectory(std::string const &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 C:\App\bin\engine_test.exe, the default drivers directory would be C:\App\drivers. (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.

Windows note: this will accept a path in the 8bit local file name encoding, which will not be able to represent all possible Unicode characters that may be used on Windows. Please use the override that accepts a std::wstring instead if possible, in order to supply a wide name.

Parameters

  • directory: The driver base directory

inline void setDriverBaseDirectory(std::wstring const &directory)

Set the driver base directory (wide/Unicode variant for Windows)

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 C:\App\bin\engine_test.exe, the default drivers directory would be C:\App\drivers. (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.

This variant is only available on Windows to specify wide/Unicode paths.

Parameters

  • directory: The driver base directory

inline void setDriverIsolationExecutable(std::string const &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 C:\App\bin\engine_test.exe on Windows, the default driver isolation path is assumed to be C:\App\bin\fluxDriverIsolation.exe. 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.

Windows note: this will accept a path in the 8bit local file name encoding, which will not be able to represent all possible Unicode characters that may be used on Windows. Please use the override that accepts a std::wstring instead if possible, in order to supply a wide name.

Parameters

  • executable: The path to the fluxDriverIsolation executable

inline void setDriverIsolationExecutable(std::wstring const &executable)

Set the path to the driver isolation executable (wide/Unicode variant for Windows)

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 C:\App\bin\engine_test.exe on Windows, the default driver isolation path is assumed to be C:\App\bin\fluxDriverIsolation.exe. 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.

This variant is only available on Windows to specify wide/Unicode paths.

Parameters

  • executable: The path to the fluxDriverIsolation executable