Class IloCplex::CallbackI

This is the abstract base class for user-written callback classes. It provides their common application programming interface (API). Callbacks may be called repeatedly at various points during an optimization; for each place a callback is called, ILOG CPLEX provides a separate callback class (derived from this class). Such a callback class provides the specific API as a protected method to use for the particular implementation.

You do not create instances of this class; rather, you use one of its child classes to implement your own callback. In order to implement your user-written callbacks with an instance of IloCplex, you should follow these steps:

1. Determine which kind of callback you want to write, and choose the appropriate class for it. The class hierarchy in Tree may give you some ideas here.
2. Derive your own subclass, MyCallbackI, say, from the appropriate predefined callback class.
3. In your subclass of the callback class, use the protected API defined in the base class to implement the main routine of your user-written callback. (All constructors of predefined callback classes are protected; they can be called only from user-written derived subclasses.)
4. In your subclass, implement the method duplicateCallback.
5. Write a function myCallback, say, that creates an instance of your implementation class in the Concert Technology environment and returns it as a handle of IloCplex::Callback.
6. Create an instance of your callback class and pass it to the member function IloCplex::use.

You can use one instance of a callback with only one instance of IloCplex. When you use a callback with a second instance of IloCplex, a copy will be automatically created using the method duplicateCallback, and that copy will be used instead.

Also, an instance of IloCplex takes account of only one instance of a particular callback at any given time. That is, if you call IloCplex::use more than once with the same class of callback, the last call overrides any previous one. For example, you can use only one primal simplex callback at a time, or you can use only one network callback at a time; and so forth.

There are two varieties of callbacks:

• Query callbacks enable your application to retrieve information about the current solution in an instance of IloCplex. The information available depends on the algorithm (primal simplex, dual simplex, barrier, mixed integer, or network) that you are using. For example, a query callback can return the current objective value, the number of simplex iterations that have been completed, and other details. Query callbacks can also be called from presolve, probing, fractional cuts, and disjunctive cuts.
• Control callbacks enable you to direct the search when you are solving a MIP in an instance of IloCplex. For example, control callbacks enable you to select the next node to process or to control the creation of subnodes (among other possibilities).

Existing extractables should never be modified within a callback. Temporary extractables, such as arrays, expressions, and range constraints, can be created and modified. Temporary extractables are often useful, for example, for computing cuts.

This method instructs CPLEX to stop the current optimization after the user callback finishes. Note that executing additional IloCplex callback methods in the callback can lead to unpredictable behavior. For example, callback methods such as IloCplex::SolveCallbackI::solve or IloCplex::BranchCallbackI::makeBranch can overwrite the callback status and thus enable the optimization to continue. Therefore, to abort an optimization effectively, a user should exit the callback by one of the following ways:

• Call return immediately after the call of abort.
• Structure the callback so that it calls no additional methods of IloCplex::CallbackI and its subclasses after abort.

This virtual method must be implemented to create a copy of the invoking callback object on the same environment. Typically the following implementation will work for a callback class called MyCallbackI:

 IloCplex::CallbackI* MyCallbackI::duplicateCallback() const {

   return (new (getEnv()) MyCallbackI(*this));

 } 

This method is called by an IloCplex object in two cases:

• When cplex.use(cb) is called for a callback object cb that is already used by another instance of IloCplex, a copy of the implementation object of cb is created by calling duplicateCallback and used in its place. The method use will return a handle to that copy.
• When a parallel optimizer is used, IloCplex creates copies of every callback that it uses by calling duplicateCallback. One copy of a callback is created for each additional thread being used in the parallel optimizer. During the optimization, each thread will invoke the copy corresponding to the thread number. The methods provided by the callback APIs are guaranteed to be threadsafe. However, when accessing parameters passed to callbacks or members stored in a callback, it is up to the user to make sure of thread safety by synchronizing access or creating distinct copies of the data in the implementation of duplicateCallback.

This method returns the environment belonging to the IloCplex object that invoked the method main.

This virtual method is to be implemented by the user in a derived callback class to define the functionality of the callback. When an instance of IloCplex uses a callback (an instance of IloCplex::CallbackI or one of its derived subclasses), IloCplex calls this virtual method main at the point during the optimization at which the callback is executed.