source: trunk/Cbc/src/CbcEventHandler.hpp

Last change on this file was 2467, checked in by unxusr, 7 weeks ago

spaces after angles

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.6 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 2467 2019-01-03 21:26:29Z stefan $
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 2467 2019-01-03 21:26:29Z stefan $
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  /*! \brief Events known to cbc */
86
87  enum CbcEvent { /*! Processing of the current node is complete. */
88    node = 200,
89    /*! A tree status interval has arrived. */
90    treeStatus,
91    /*! A solution has been found. */
92    solution,
93    /*! A heuristic solution has been found. */
94    heuristicSolution,
95    /*! A solution will be found unless user takes action (first check). */
96    beforeSolution1,
97    /*! A solution will be found unless user takes action (thorough check). */
98    beforeSolution2,
99    /*! After failed heuristic. */
100    afterHeuristic,
101    /*! On entry to small branch and bound. */
102    smallBranchAndBound,
103    /*! After a pass of heuristic. */
104    heuristicPass,
105    /*! When converting constraints to cuts. */
106    convertToCuts,
107    /*! Having generated cuts, allows user to think. */
108    generatedCuts,
109    /*! End of search. */
110    endSearch
111  };
112
113  /*! \brief Action codes returned by the event handler.
114
115        Specific values are chosen to match ClpEventHandler return codes.
116    */
117
118  enum CbcAction { /*! Continue --- no action required. */
119    noAction = -1,
120    /*! Stop --- abort the current run at the next opportunity. */
121    stop = 0,
122    /*! Restart --- restart branch-and-cut search; do not undo root node
123        processing.
124        */
125    restart,
126    /*! RestartRoot --- undo root node and start branch-and-cut afresh. */
127    restartRoot,
128    /*! Add special cuts. */
129    addCuts,
130    /*! Pretend solution never happened. */
131    killSolution,
132    /*! Take action on modified data. */
133    takeAction
134
135  };
136
137  /*! \brief Data type for event/action pairs */
138
139  typedef std::map< CbcEvent, CbcAction > eaMapPair;
140
141  /*! \name Event Processing */
142  //@{
143
144  /*! \brief Return the action to be taken for an event.
145
146      Return the action that should be taken in response to the event passed as
147      the parameter. The default implementation simply reads a return code
148      from a map.
149    */
150  virtual CbcAction event(CbcEvent whichEvent);
151
152  /*! \brief Return the action to be taken for an event - and modify data.
153
154      Return the action that should be taken in response to the event passed as
155      the parameter. The default implementation simply reads a return code
156      from a map.
157    */
158  virtual CbcAction event(CbcEvent whichEvent, void *data);
159
160  //@}
161
162  /*! \name Constructors and destructors */
163  //@{
164
165  /*! \brief Default constructor. */
166
167  CbcEventHandler(CbcModel *model = 0 /* was NULL but 4.6 complains */);
168
169  /*! \brief Copy constructor. */
170
171  CbcEventHandler(const CbcEventHandler &orig);
172
173  /*! \brief Assignment. */
174
175  CbcEventHandler &operator=(const CbcEventHandler &rhs);
176
177  /*! \brief Clone (virtual) constructor. */
178
179  virtual CbcEventHandler *clone() const;
180
181  /*! \brief Destructor. */
182
183  virtual ~CbcEventHandler();
184
185  //@}
186
187  /*! \name Set/Get methods */
188  //@{
189
190  /*! \brief Set model. */
191
192  inline void setModel(CbcModel *model)
193  {
194    model_ = model;
195  }
196
197  /*! \brief Get model. */
198
199  inline const CbcModel *getModel() const
200  {
201    return model_;
202  }
203
204  /*! \brief Set the default action */
205
206  inline void setDfltAction(CbcAction action)
207  {
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  {
215    if (eaMap_ == 0) {
216      eaMap_ = new eaMapPair;
217    }
218    (*eaMap_)[event] = action;
219  }
220
221  //@}
222
223protected:
224  /*! \name Data members
225
226       Protected (as opposed to private) to allow access by derived classes.
227    */
228  //@{
229
230  /*! \brief Pointer to associated CbcModel */
231
232  CbcModel *model_;
233
234  /*! \brief Default action */
235
236  CbcAction dfltAction_;
237
238  /*! \brief Pointer to a map that holds non-default event/action pairs */
239
240  eaMapPair *eaMap_;
241
242  //@}
243};
244
245#endif
246
247/* vi: softtabstop=2 shiftwidth=2 expandtab tabstop=2
248*/
Note: See TracBrowser for help on using the repository browser.