CPXXcallbacksetfunc and CPXcallbacksetfunc

Sets the generic callback function and specifies in which contexts it will be invoked.

int CPXXcallbacksetfunc ( CPXENVptr env, CPXLPptr lp, CPXLONG contextmask, CPXCALLBACKFUNC *callback, void * userhandle )

int CPXcallbacksetfunc ( CPXENVptr env, CPXLPptr lp, CPXLONG contextmask, CPXCALLBACKFUNC *callback, void * userhandle )

Description

The generic callback function is a callback function that is invoked in many different places during the search. In contrast to the legacy CPLEX callback functions, it is not a dedicated callback (for example, dedicated to separate a cut) but rather a multi-purpose function. What your application can reasonably do in a callback invocation is defined by the context in which the callback is invoked. This context is specified by the contextid argument to the callback.

For a detailed explanation of the various contexts in which the callback can be invoked refer to the documentation of the following constants:

These constants can also be combined by means of a bit-wise OR with the value of the contextmask argument passed to that routine.

For a list of differences between a generic callback and the legacy callbacks of CPLEX, see this topic What is a generic callback? in the CPLEX User's Manual.

With an appropriate context, you can use a generic callback to monitor progress of the solution process (CPX_CALLBACKCONTEXT_LOCAL_PROGRESS, CPX_CALLBACKCONTEXT_GLOBAL_PROGRESS) as well as to control or guide the solution process (CPXXcallbackpostheursoln and CPXcallbackpostheursoln, CPX_CALLBACKCONTEXT_CANDIDATE, CPX_CALLBACKCONTEXT_RELAXATION, CPX_CALLBACKCONTEXT_BRANCHING).

For more detail about other purpose of a generic callback, see the topic What can you do with a generic callback? in the CPLEX User's Manual.

Contexts in which CPLEX invokes the generic callback

Context	Description
CPX_CALLBACKCONTEXT_THREAD_UP	Invoked when CPLEX starts a new thread. This context offers the user an opportunity to set up thread-local data if necessary.
CPX_CALLBACKCONTEXT_THREAD_DOWN	Invoked when CPLEX tears down a thread (that was previously announced with CPX_CALLBACKCONTEXT_THREAD_UP). This context offers the user an opportunity to tear down thread-local data if necessary.
CPX_CALLBACKCONTEXT_LOCAL_PROGRESS	Invoked to inform the application about thread-local progress in the search. The user can query progress information with these routines: CPXXcallbackgetinfodbl and CPXcallbackgetinfodbl, CPXXcallbackgetinfoint and CPXcallbackgetinfoint, CPXXcallbackgetinfolong and CPXcallbackgetinfolong. The user can also inject feasible solutions by means of CPXXcallbackpostheursoln and CPXcallbackpostheursoln. The user can also halt the search with CPXXcallbackabort and CPXcallbackabort.
CPX_CALLBACKCONTEXT_GLOBAL_PROGRESS	Invoked to inform the application about global progress in the search. The user can query progress information with these routines: CPXXcallbackgetinfodbl and CPXcallbackgetinfodbl, CPXXcallbackgetinfoint and CPXcallbackgetinfoint, CPXXcallbackgetinfolong and CPXcallbackgetinfolong. The user can also inject feasible solutions by means of CPXXcallbackpostheursoln and CPXcallbackpostheursoln. The user can also halt the search with CPXXcallbackabort and CPXcallbackabort. Attention! In a multi-threaded application, invocation of a generic callback holds a lock. Consequently, the generic callback is implicitly thread-safe. However, lengthy computations in the callback will block other threads during this lock.
CPX_CALLBACKCONTEXT_CANDIDATE	Invoked when CPLEX has found a candidate feasible solution. The user can query the proposed solution by means of CPXXcallbackgetcandidatepoint and CPXcallbackgetcandidatepoint and reject the candidate if necessary by means of CPXXcallbackrejectcandidate and CPXcallbackrejectcandidate.
CPX_CALLBACKCONTEXT_RELAXATION	Invoked when CPLEX has found a relaxed solution (usually not integer feasible). For example, the solution perhaps came from a node LP relaxation, but the solution can also come from other places as well. The user can query the relaxed solution by means of CPXXcallbackgetrelaxationpoint and CPXcallbackgetrelaxationpoint and can, for instance, add user cuts by means of CPXXcallbackaddusercuts and CPXcallbackaddusercuts.
CPX_CALLBACKCONTEXT_BRANCHING	Invoked when CPLEX is done processing a node and has to decide how to branch. The user can query the relaxed solution of the node by means of CPXXcallbackgetrelaxationpoint and CPXcallbackgetrelaxationpoint, and can specify a custom branching by means of CPXXcallbackprunenode and CPXcallbackprunenode or CPXXcallbackmakebranch and CPXcallbackmakebranch.

The generic callback and multi-threading

For special considerations about the generic callback and multi-threaded applications, see the topic What is a generic callback? in the CPLEX User's Manual.

Special considerations

You must not mix the generic callback with legacy callbacks. If you install both generic and legacy callbacks, then CPLEX raises an error as soon as you call any optmization function, such as CPXXmipopt and CPXmipopt or CPXXlpopt and CPXlpopt or other optimization routines.

In order to clear a generic callback, invoke this function with a contextmask of 0 (zero) or a callback of NULL.

Code in a generic callback function can invoke only routines that take a context pointer (CPXCALLBACKCONTEXTptr) as an argument. Calling other CPLEX routines (especially those taking a pointer to the environment (CPXENVptr) or a pointer to an LP problem (CPXLPptr) as an argument results in undefined behavior.

Arguments

env: A pointer to the CPLEX environment as returned by CPXXopenCPLEX/CPXopenCPLEX.
lp: A pointer to a CPLEX problem object as returned, for example, by CPXXcreateprob/CPXcreateprob.
contextmask: Specifies in which context CPLEX should invoke the callback. This value can be the bit-wise OR of the various constants that define the generic callback contexts.
callback: The user-written callback function to invoke. See CPXCALLBACKFUNC for the signature of this function.
userhandle: User data for callback invocation. CPLEX passes this pointer as the last argument to the callback function.

Return

The routine returns 0 (zero) if successful and nonzero if an error occurs.