Luxand FaceCrop SDK –Thread Safety and Contexts
This chapter describes the use of FaceCrop SDK in applications, processing multiple threads. If your program is executed in a single thread (by default it happens in almost all environments, except PHP), you can skip this chapter.
The FaceCrop SDK library can be used in multithread applications. All its functions are thread-safe, except the following:
fcActivate
fcFinalize
However if your application is multithreaded, you need to take into account that calling any function that sets face detection parameters (e.g. fcSetFaceScale) has impact on all threads. Therefore FaceCrop SDK has the mechanism of contexts. This mechanism allows setting parameters of detection for each thread separately.
As you work with contexts, you need to use special variants of functions with postfix “_C”. Functions with this postfix as the final parameter accept context ID. These variants of functions are determined for all functions of FaceCrop SDK, except:
fcActivate
fcCreateContextID
fcFreeContextID
fcFinalize
Syntax of calling a function with postfix “_C” is distinguished only by presence of an additional parameter (context ID). For example, for the following function:
int fcFaceCrop(char * inFileName, char * outFileName, int width, int height);
the corresponding function working with context will be:
int fcFaceCrop_C(char * inFileName, char * outFileName, int width, int height, int ContextID);
If context ID is not specified (function without postfix “_C” is called), the function is considered to be working in special context “by default”.
Contexts are created with the fcCreateContextID call and freed with fcFreeContextID call.
To work with contexts, it is necessary to follow these steps:
1. Call fcActivate
2. Using the fcCreateContextID function, you need to get ContextID in each thread and then transfer it to the FaceCrop functions, which are used.
3. On finishing work with FaceCrop in the thread it is necessary to call the fcFreeContextID function in this thread.
4. Call fcFinalize
The context mechanism is used in all functions of the PHP extension because in many realizations of the PHP interpreter, end-user applications are executed in different threads of one interpreter. More detailed information can be found in the Using with PHP chapter of the Using FaceCrop with Programming Languages chapter. chapter of the Using FaceCrop with Programming Languages chapter.
fcCreateContextID Function
Creates a context ID.
C++ Syntax:
int fcCreateContextID(ref int ContextID);
Delphi Syntax:
function fcCreateContextID(ContextID: PInteger): integer;
C# Syntax:
int fc.CreateContextID(ref int ContextID);
PHP Syntax:
int fcCreateContextID(void);
VB Syntax:
Function fcVBCreateContextID(ByRef contextID As Long) As Long
Parameters:
ContextID – context ID for current thread.
Return Value:
Returns fcErrorOk if successful.
fcFreeContextID Function
Frees a context ID.
C++ Syntax:
int fcFreeContextID(int ContextID);
Delphi Syntax:
function fcFreeContextID(ContextID: integer): integer;
C# Syntax:
int fc.FreeContextID(int ContextID);
PHP Syntax:
int fcFreeContextID(int $ContextID);
VB Syntax:
Function fcVBFreeContextID(ByVal contextID As Long) As Long
Parameters:
ContextID – context ID for current thread.
Return Value:
Returns fcErrorOk if successful.