Class IloCplex::CallbackI

This is the abstract base class for user-written legacy 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, 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, 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. Your derived class must inherit from only one predefined callback class; that is multiple inheritance is not allowed.
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 that creates an instance of your implementation class in the Concert Technology environment, so that the instance and data structures used internally by that instance are de-allocated by IloEnv::end. The function that you write should return the instance as a handle of IloCplex::Callback. When you write your callback function, use the placement operator new to specify the environment, like this:

            MyCallback *myCallback = new(env) MyCallback(env, y, 0, 0);
        

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 a time stamp, useful in measuring elapsed time in seconds.

To measure time spent between a starting point and ending point of an operation, take the result of this method at the starting point; take the result of this method at the end point; subtract the starting time stamp from the ending time stamp; the subtraction yields elapsed time in seconds.

Whether the elapsed time measures wall clock time (also known as real time) or CPU time depends on the setting of the clock type parameter ClockType.

The absolute value of the time stamp is not meaningful.

This method returns a deterministic time stamp in ticks.

To measure elapsed deterministic time in ticks between a starting point and ending point of an operation, take the deterministic time stamp at the starting point; take the deterministic time stamp at the ending point; subtract the starting deterministic time stamp from the ending deterministic time stamp.

The absolute value of the deterministic time stamp is not meaningful.

This method returns a deterministic time stamp specifying when the deterministic time limit will occur. To compute remaining time in ticks, subtract the result of getDetTime from the result of this method.

The absolute value of the deterministic time stamp is not meaningful.

This method returns a time stamp specifying when the time limit will occur. To compute remaining time in seconds, subtract the result of getCplexTime from the result of this method. This computation yields either wall clock time (also known as real time) or CPU time, depending on the clock type set by the parameter ClockType. The absolute value of the time stamp is not meaningful.

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

This method returns a deterministic time stamp specifying when the solving process was started. To compute elapsed time in ticks, subtract the result of getDetTime from the result of this method.

The absolute value of the deterministic time stamp is not meaningful.

This method returns a time stamp specifying when the solving process was started. To compute elapsed time in seconds, subtract the result of getCplexTime from the result of this method. This computation yields either wall clock time (also known as real time) or CPU time, depending on the clock type set by the parameter ClockType. The absolute value of the time stamp is not meaningful.

This method returns the callback type of the invoking callback object.

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.