source: trunk/Cbc/src/CbcEventHandler.hpp @ 2286

Last change on this file since 2286 was 2286, checked in by forrest, 3 years ago

add event

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.8 KB
Line 
1/*
2  Copyright (C) 2006, International Business Machines Corporation and others.
3  All Rights Reserved.
4
5  This code is licensed under the terms of the Eclipse Public License (EPL).
6
7  $Id: CbcEventHandler.hpp 2286 2016-08-15 10:19:41Z forrest $
8*/
9
10#ifndef CbcEventHandler_H
11#define CbcEventHandler_H
12
13/*! \file CbcEventHandler.hpp
14    \brief Event handling for cbc
15
16  This file contains the declaration of CbcEventHandler, used for event
17  handling in cbc.
18
19  The central method is CbcEventHandler::event(). The default semantics of
20  this call are `ask for the action to take in reponse to this event'. The
21  call is made at the point in the code where the event occurs (<i>e.g.</i>,
22  when a solution is found, or when a node is added to or removed from the
23  search tree). The return value specifies the action to perform in response
24  to the event (<i>e.g.</i>, continue, or stop).
25
26  This is a lazy class. Initially, it knows nothing about specific events,
27  and returns dfltAction_ for any event. This makes for a trivial constructor
28  and fast startup. The only place where the list of known events or actions
29  is hardwired is in the enum definitions for CbcEvent and CbcAction,
30  respectively.
31
32  At the first call to setAction, a map is created to hold (Event,Action)
33  pairs, and this map will be consulted ever after. Events not in the map
34  will still return the default value.
35
36  For serious extensions, derive a subclass and replace event() with a
37  function that suits you better.  The function has access to the CbcModel
38  via a pointer held in the CbcEventHandler object, and can do as much
39  thinking as it likes before returning an answer.  You can also print as
40  much information as you want. The model is held as a const, however, so
41  you can't alter reality.
42
43  The design of the class deliberately matches ClpEventHandler, so that other
44  solvers can participate in cbc without breaking the patterns set by
45  clp-specific code.
46
47*/
48
49#include <cstddef>
50#include <map>
51
52/* May well already be declared, but can't hurt. */
53
54class CbcModel ;
55
56/*
57  cvs/svn: $Id: CbcEventHandler.hpp 2286 2016-08-15 10:19:41Z forrest $
58*/
59
60/*! \class CbcEventHandler
61    \brief Base class for Cbc event handling.
62
63  Up front: We're not talking about unanticipated events here. We're talking
64  about anticipated events, in the sense that the code is going to make a call
65  to event() and is prepared to obey the return value that it receives.
66
67  The general pattern for usage is as follows:
68  <ol>
69    <li> Create a CbcEventHandler object. This will be initialised with a set
70         of default actions for every recognised event.
71
72    <li> Attach the event handler to the CbcModel object.
73
74    <li> When execution reaches the point where an event occurs, call the
75         event handler as CbcEventHandler::event(the event). The return value
76         will specify what the code should do in response to the event.
77  </ol>
78
79  The return value associated with an event can be changed at any time.
80*/
81
82class CbcEventHandler {
83
84public:
85
86    /*! \brief Events known to cbc */
87
88    enum CbcEvent { /*! Processing of the current node is complete. */
89        node = 200,
90        /*! A tree status interval has arrived. */
91        treeStatus,
92        /*! A solution has been found. */
93        solution,
94        /*! A heuristic solution has been found. */
95        heuristicSolution,
96        /*! A solution will be found unless user takes action (first check). */
97        beforeSolution1,
98        /*! A solution will be found unless user takes action (thorough check). */
99        beforeSolution2,
100        /*! After failed heuristic. */
101        afterHeuristic,
102        /*! On entry to small branch and bound. */
103        smallBranchAndBound,
104        /*! After a pass of heuristic. */
105        heuristicPass,
106        /*! When converting constraints to cuts. */
107        convertToCuts,
108        /*! Having generated cuts, allows user to think. */
109        generatedCuts,
110        /*! End of search. */
111        endSearch
112    } ;
113
114    /*! \brief Action codes returned by the event handler.
115
116        Specific values are chosen to match ClpEventHandler return codes.
117    */
118
119    enum CbcAction { /*! Continue --- no action required. */
120        noAction = -1,
121        /*! Stop --- abort the current run at the next opportunity. */
122        stop = 0,
123        /*! Restart --- restart branch-and-cut search; do not undo root node
124        processing.
125        */
126        restart,
127        /*! RestartRoot --- undo root node and start branch-and-cut afresh. */
128        restartRoot,
129        /*! Add special cuts. */
130        addCuts,
131        /*! Pretend solution never happened. */
132        killSolution,
133        /*! Take action on modified data. */
134        takeAction
135
136    } ;
137
138    /*! \brief Data type for event/action pairs */
139
140    typedef std::map<CbcEvent, CbcAction> eaMapPair ;
141
142
143    /*! \name Event Processing */
144    //@{
145
146    /*! \brief Return the action to be taken for an event.
147
148      Return the action that should be taken in response to the event passed as
149      the parameter. The default implementation simply reads a return code
150      from a map.
151    */
152    virtual CbcAction event(CbcEvent whichEvent) ;
153
154    /*! \brief Return the action to be taken for an event - and modify data.
155
156      Return the action that should be taken in response to the event passed as
157      the parameter. The default implementation simply reads a return code
158      from a map.
159    */
160    virtual CbcAction event(CbcEvent whichEvent, void * data) ;
161
162    //@}
163
164
165    /*! \name Constructors and destructors */
166    //@{
167
168    /*! \brief Default constructor. */
169
170    CbcEventHandler(CbcModel *model = 0 /* was NULL but 4.6 complains */) ;
171
172    /*! \brief Copy constructor. */
173
174    CbcEventHandler(const CbcEventHandler &orig) ;
175
176    /*! \brief Assignment. */
177
178    CbcEventHandler& operator=(const CbcEventHandler &rhs) ;
179
180    /*! \brief Clone (virtual) constructor. */
181
182    virtual CbcEventHandler* clone() const ;
183
184    /*! \brief Destructor. */
185
186    virtual ~CbcEventHandler() ;
187
188    //@}
189
190    /*! \name Set/Get methods */
191    //@{
192
193    /*! \brief Set model. */
194
195    inline void setModel(CbcModel *model) {
196        model_ = model ;
197    }
198
199    /*! \brief Get model. */
200
201    inline const CbcModel* getModel() const {
202        return model_ ;
203    }
204
205    /*! \brief Set the default action */
206
207    inline void setDfltAction(CbcAction action) {
208        dfltAction_ = action ;
209    }
210
211    /*! \brief Set the action code associated with an event */
212
213    inline void setAction(CbcEvent event, CbcAction action) {
214        if (eaMap_ == 0) {
215            eaMap_ = new eaMapPair ;
216        }
217        (*eaMap_)[event] = action ;
218    }
219
220    //@}
221
222
223protected:
224
225    /*! \name Data members
226
227       Protected (as opposed to private) to allow access by derived classes.
228    */
229    //@{
230
231    /*! \brief Pointer to associated CbcModel */
232
233    CbcModel *model_ ;
234
235    /*! \brief Default action */
236
237    CbcAction dfltAction_ ;
238
239    /*! \brief Pointer to a map that holds non-default event/action pairs */
240
241    eaMapPair *eaMap_ ;
242
243    //@}
244} ;
245
246#endif
247
Note: See TracBrowser for help on using the repository browser.