Native external functions: Thread safety

OrcaFlex external functions should be thread safe. Behind this simple, blanket statement lie a number of complications which shall be explained below. However, if you ensure that your external function is itself thread safe then the issues described below can simply be ignored.

External functions called from OrcaFlex

The most common case to consider is that of an external function being called from the OrcaFlex GUI.

OrcaFlex is capable of multithreading which it can use to speed up simulations. OrcaFlex maintains a pool of threads for performing calculations. If your machine has only a single processing unit then, by default, only a single thread will be used and no multithreading is performed. If your machine has multiple processing units then, by default, OrcaFlex will perform calculations with one thread per processing unit.

Note that only the line calculations in OrcaFlex are multithreaded. Furthermore, OrcaFlex will do the calculations for a single line in the same thread. So, different lines may be calculated in different threads, but different nodes in the same line will always be calculated in the same thread. External functions for objects other than lines will not be called concurrently and thread safety issues can be ignored. However, this state of affairs is likely to change as we implement multithreading more widely in OrcaFlex. So, to protect against future incompatibilities, we recommend that you implement all external functions under the assumption that they may be called from multiple threads concurrently.

External functions for lines

As explained above, external functions for lines (e.g. axial stiffness or bend stiffness) can be called concurrently from different threads and so need to be thread safe.

If your external function makes calls into OrcFxAPI then this would appear to present a problem since OrcFxAPI does not support multiple threads operating on the same model concurrently. However, when OrcFxAPI is called from an external function, these calls are protected by critical sections and thus can be assumed to be thread safe.

Note: This is a potential performance bottleneck because these calls will be processed sequentially. Because of this you should avoid calls back to OrcFxAPI where possible.

External functions called from OrcFxAPI

The sections above apply equally to simulations being run through OrcFxAPI (e.g. calls to C_RunSimulation2). However, certain exemptions apply to Distributed OrcaFlex, as explained below.

External functions called from Distributed OrcaFlex

Thread safety issue arise when the Distributed OrcaFlex client program runs on a multi-processor machine. In this case the client program processes multiple jobs in parallel with one thread per job using OrcFxAPI to run the simulations.

If the jobs being run by Distributed OrcaFlex use external functions then the external function DLL will be loaded by the client program. On a multi-processor machine this can result in the same external function DLL being loaded by different job processing threads of the client program. When this happens the external function DLL has single code and data segments shared by each processing thread and because of this the external function must be thread safe.

Multithreading in your external function

It is conceivable, although unlikely, that the calculation performed in an external function is itself multithreaded. This is allowed, but with the proviso that any calls to OrcFxAPI functions must be made from the thread which called the external function.

See also

Native External Functions, Axial Stiffness, Bend Stiffness, Torsional Stiffness.