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

Last change on this file since 1432 was 1432, checked in by bjarni, 11 years ago

Added extra return at end of each source file where needed, to remove possible linefeed conflicts (NightlyBuild? errors)

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