Scippy

SCIP

Solving Constraint Integer Programs

scip_event.h
Go to the documentation of this file.
1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
2 /* */
3 /* This file is part of the program and library */
4 /* SCIP --- Solving Constraint Integer Programs */
5 /* */
6 /* Copyright (C) 2002-2021 Konrad-Zuse-Zentrum */
7 /* fuer Informationstechnik Berlin */
8 /* */
9 /* SCIP is distributed under the terms of the ZIB Academic License. */
10 /* */
11 /* You should have received a copy of the ZIB Academic License */
12 /* along with SCIP; see the file COPYING. If not visit scipopt.org. */
13 /* */
14 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
15 
16 /**@file scip_event.h
17  * @ingroup PUBLICCOREAPI
18  * @brief public methods for event handler plugins and event handlers
19  * @author Tobias Achterberg
20  * @author Timo Berthold
21  * @author Thorsten Koch
22  * @author Alexander Martin
23  * @author Marc Pfetsch
24  * @author Kati Wolter
25  * @author Gregor Hendel
26  * @author Leona Gottwald
27  */
28 
29 /*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
30 
31 #ifndef __SCIP_SCIP_EVENT_H__
32 #define __SCIP_SCIP_EVENT_H__
33 
34 
35 #include "scip/def.h"
36 #include "scip/type_event.h"
37 #include "scip/type_lp.h"
38 #include "scip/type_retcode.h"
39 #include "scip/type_scip.h"
40 #include "scip/type_var.h"
41 
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45 
46 /**@addtogroup PublicEventHandlerMethods
47  *
48  * @{
49  */
50 
51 /** creates an event handler and includes it in SCIP
52  *
53  * @note method has all event handler callbacks as arguments and is thus changed every time a new
54  * callback is added in future releases; consider using SCIPincludeEventhdlrBasic() and setter functions
55  * if you seek for a method which is less likely to change in future releases
56  */
59  SCIP* scip, /**< SCIP data structure */
60  const char* name, /**< name of event handler */
61  const char* desc, /**< description of event handler */
62  SCIP_DECL_EVENTCOPY ((*eventcopy)), /**< copy method of event handler or NULL if you don't want to copy your plugin into sub-SCIPs */
63  SCIP_DECL_EVENTFREE ((*eventfree)), /**< destructor of event handler */
64  SCIP_DECL_EVENTINIT ((*eventinit)), /**< initialize event handler */
65  SCIP_DECL_EVENTEXIT ((*eventexit)), /**< deinitialize event handler */
66  SCIP_DECL_EVENTINITSOL((*eventinitsol)), /**< solving process initialization method of event handler */
67  SCIP_DECL_EVENTEXITSOL((*eventexitsol)), /**< solving process deinitialization method of event handler */
68  SCIP_DECL_EVENTDELETE ((*eventdelete)), /**< free specific event data */
69  SCIP_DECL_EVENTEXEC ((*eventexec)), /**< execute event handler */
70  SCIP_EVENTHDLRDATA* eventhdlrdata /**< event handler data */
71  );
72 
73 /** creates an event handler and includes it in SCIP with all its non-fundamental callbacks set
74  * to NULL; if needed, non-fundamental callbacks can be set afterwards via setter functions
75  * SCIPsetEventhdlrCopy(), SCIPsetEventhdlrFree(), SCIPsetEventhdlrInit(), SCIPsetEventhdlrExit(),
76  * SCIPsetEventhdlrInitsol(), SCIPsetEventhdlrExitsol(), and SCIPsetEventhdlrDelete()
77  *
78  * @note if you want to set all callbacks with a single method call, consider using SCIPincludeEventhdlr() instead
79  */
82  SCIP* scip, /**< SCIP data structure */
83  SCIP_EVENTHDLR** eventhdlrptr, /**< reference to an event handler, or NULL */
84  const char* name, /**< name of event handler */
85  const char* desc, /**< description of event handler */
86  SCIP_DECL_EVENTEXEC ((*eventexec)), /**< execute event handler */
87  SCIP_EVENTHDLRDATA* eventhdlrdata /**< event handler data */
88  );
89 
90 /** sets copy callback of the event handler */
93  SCIP* scip, /**< scip instance */
94  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
95  SCIP_DECL_EVENTCOPY ((*eventcopy)) /**< copy callback of the event handler */
96  );
97 
98 /** sets deinitialization callback of the event handler */
101  SCIP* scip, /**< scip instance */
102  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
103  SCIP_DECL_EVENTFREE ((*eventfree)) /**< deinitialization callback of the event handler */
104  );
105 
106 /** sets initialization callback of the event handler */
109  SCIP* scip, /**< scip instance */
110  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
111  SCIP_DECL_EVENTINIT ((*eventinit)) /**< initialize event handler */
112  );
113 
114 /** sets deinitialization callback of the event handler */
117  SCIP* scip, /**< scip instance */
118  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
119  SCIP_DECL_EVENTEXIT ((*eventexit)) /**< deinitialize event handler */
120  );
121 
122 /** sets solving process initialization callback of the event handler */
125  SCIP* scip, /**< scip instance */
126  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
127  SCIP_DECL_EVENTINITSOL((*eventinitsol)) /**< solving process initialization callback of event handler */
128  );
129 
130 /** sets solving process deinitialization callback of the event handler */
133  SCIP* scip, /**< scip instance */
134  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
135  SCIP_DECL_EVENTEXITSOL((*eventexitsol)) /**< solving process deinitialization callback of event handler */
136  );
137 
138 /** sets callback of the event handler to free specific event data */
141  SCIP* scip, /**< scip instance */
142  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
143  SCIP_DECL_EVENTDELETE ((*eventdelete)) /**< free specific event data */
144  );
145 
146 /** returns the event handler of the given name, or NULL if not existing */
149  SCIP* scip, /**< SCIP data structure */
150  const char* name /**< name of event handler */
151  );
152 
153 /** returns the array of currently available event handlers */
156  SCIP* scip /**< SCIP data structure */
157  );
158 
159 /** returns the number of currently available event handlers */
162  SCIP* scip /**< SCIP data structure */
163  );
164 
165 /** @} */
166 
167 /**@addtogroup PublicEventMethods
168  *
169  * @{
170  */
171 
172 /** catches a global (not variable or row dependent) event
173  *
174  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
175  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
176  *
177  * @pre This method can be called if @p scip is in one of the following stages:
178  * - \ref SCIP_STAGE_TRANSFORMING
179  * - \ref SCIP_STAGE_TRANSFORMED
180  * - \ref SCIP_STAGE_INITPRESOLVE
181  * - \ref SCIP_STAGE_PRESOLVING
182  * - \ref SCIP_STAGE_EXITPRESOLVE
183  * - \ref SCIP_STAGE_PRESOLVED
184  * - \ref SCIP_STAGE_INITSOLVE
185  * - \ref SCIP_STAGE_SOLVING
186  * - \ref SCIP_STAGE_SOLVED
187  * - \ref SCIP_STAGE_EXITSOLVE
188  * - \ref SCIP_STAGE_FREETRANS
189  */
192  SCIP* scip, /**< SCIP data structure */
193  SCIP_EVENTTYPE eventtype, /**< event type mask to select events to catch */
194  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
195  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
196  int* filterpos /**< pointer to store position of event filter entry, or NULL */
197  );
198 
199 /** drops a global event (stops to track event)
200  *
201  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
202  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
203  *
204  * @pre This method can be called if @p scip is in one of the following stages:
205  * - \ref SCIP_STAGE_TRANSFORMING
206  * - \ref SCIP_STAGE_TRANSFORMED
207  * - \ref SCIP_STAGE_INITPRESOLVE
208  * - \ref SCIP_STAGE_PRESOLVING
209  * - \ref SCIP_STAGE_EXITPRESOLVE
210  * - \ref SCIP_STAGE_PRESOLVED
211  * - \ref SCIP_STAGE_INITSOLVE
212  * - \ref SCIP_STAGE_SOLVING
213  * - \ref SCIP_STAGE_SOLVED
214  * - \ref SCIP_STAGE_EXITSOLVE
215  * - \ref SCIP_STAGE_FREETRANS
216  */
219  SCIP* scip, /**< SCIP data structure */
220  SCIP_EVENTTYPE eventtype, /**< event type mask of dropped event */
221  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
222  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
223  int filterpos /**< position of event filter entry returned by SCIPcatchEvent(), or -1 */
224  );
225 
226 /** catches an objective value or domain change event on the given transformed variable
227  *
228  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
229  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
230  *
231  * @pre This method can be called if @p scip is in one of the following stages:
232  * - \ref SCIP_STAGE_TRANSFORMING
233  * - \ref SCIP_STAGE_TRANSFORMED
234  * - \ref SCIP_STAGE_INITPRESOLVE
235  * - \ref SCIP_STAGE_PRESOLVING
236  * - \ref SCIP_STAGE_EXITPRESOLVE
237  * - \ref SCIP_STAGE_PRESOLVED
238  * - \ref SCIP_STAGE_INITSOLVE
239  * - \ref SCIP_STAGE_SOLVING
240  * - \ref SCIP_STAGE_SOLVED
241  * - \ref SCIP_STAGE_EXITSOLVE
242  * - \ref SCIP_STAGE_FREETRANS
243  */
246  SCIP* scip, /**< SCIP data structure */
247  SCIP_VAR* var, /**< transformed variable to catch event for */
248  SCIP_EVENTTYPE eventtype, /**< event type mask to select events to catch */
249  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
250  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
251  int* filterpos /**< pointer to store position of event filter entry, or NULL */
252  );
253 
254 /** drops an objective value or domain change event (stops to track event) on the given transformed variable
255  *
256  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
257  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
258  *
259  * @pre This method can be called if @p scip is in one of the following stages:
260  * - \ref SCIP_STAGE_TRANSFORMING
261  * - \ref SCIP_STAGE_TRANSFORMED
262  * - \ref SCIP_STAGE_INITPRESOLVE
263  * - \ref SCIP_STAGE_PRESOLVING
264  * - \ref SCIP_STAGE_EXITPRESOLVE
265  * - \ref SCIP_STAGE_PRESOLVED
266  * - \ref SCIP_STAGE_INITSOLVE
267  * - \ref SCIP_STAGE_SOLVING
268  * - \ref SCIP_STAGE_SOLVED
269  * - \ref SCIP_STAGE_EXITSOLVE
270  * - \ref SCIP_STAGE_FREETRANS
271  */
274  SCIP* scip, /**< SCIP data structure */
275  SCIP_VAR* var, /**< transformed variable to drop event for */
276  SCIP_EVENTTYPE eventtype, /**< event type mask of dropped event */
277  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
278  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
279  int filterpos /**< position of event filter entry returned by SCIPcatchVarEvent(), or -1 */
280  );
281 
282 /** catches a row coefficient, constant, or side change event on the given row
283  *
284  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
285  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
286  *
287  * @pre This method can be called if @p scip is in one of the following stages:
288  * - \ref SCIP_STAGE_TRANSFORMING
289  * - \ref SCIP_STAGE_TRANSFORMED
290  * - \ref SCIP_STAGE_INITPRESOLVE
291  * - \ref SCIP_STAGE_PRESOLVING
292  * - \ref SCIP_STAGE_EXITPRESOLVE
293  * - \ref SCIP_STAGE_PRESOLVED
294  * - \ref SCIP_STAGE_INITSOLVE
295  * - \ref SCIP_STAGE_SOLVING
296  * - \ref SCIP_STAGE_SOLVED
297  * - \ref SCIP_STAGE_EXITSOLVE
298  * - \ref SCIP_STAGE_FREETRANS
299  */
302  SCIP* scip, /**< SCIP data structure */
303  SCIP_ROW* row, /**< linear row to catch event for */
304  SCIP_EVENTTYPE eventtype, /**< event type mask to select events to catch */
305  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
306  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
307  int* filterpos /**< pointer to store position of event filter entry, or NULL */
308  );
309 
310 /** drops a row coefficient, constant, or side change event (stops to track event) on the given row
311  *
312  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
313  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
314  *
315  * @pre This method can be called if @p scip is in one of the following stages:
316  * - \ref SCIP_STAGE_TRANSFORMING
317  * - \ref SCIP_STAGE_TRANSFORMED
318  * - \ref SCIP_STAGE_INITPRESOLVE
319  * - \ref SCIP_STAGE_PRESOLVING
320  * - \ref SCIP_STAGE_EXITPRESOLVE
321  * - \ref SCIP_STAGE_PRESOLVED
322  * - \ref SCIP_STAGE_INITSOLVE
323  * - \ref SCIP_STAGE_SOLVING
324  * - \ref SCIP_STAGE_SOLVED
325  * - \ref SCIP_STAGE_EXITSOLVE
326  * - \ref SCIP_STAGE_FREETRANS
327  */
330  SCIP* scip, /**< SCIP data structure */
331  SCIP_ROW* row, /**< linear row to drop event for */
332  SCIP_EVENTTYPE eventtype, /**< event type mask of dropped event */
333  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
334  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
335  int filterpos /**< position of event filter entry returned by SCIPcatchVarEvent(), or -1 */
336  );
337 
338 /**@} */
339 
340 #ifdef __cplusplus
341 }
342 #endif
343 
344 #endif
SCIP_EXPORT int SCIPgetNEventhdlrs(SCIP *scip)
Definition: scip_event.c:249
SCIP_EXPORT SCIP_EVENTHDLR * SCIPfindEventhdlr(SCIP *scip, const char *name)
Definition: scip_event.c:225
#define SCIP_EXPORT
Definition: def.h:100
SCIP_DECL_EVENTEXIT(EventhdlrNewSol::scip_exit)
struct SCIP_EventhdlrData SCIP_EVENTHDLRDATA
Definition: type_event.h:146
SCIP_EXPORT SCIP_RETCODE SCIPsetEventhdlrInitsol(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTINITSOL((*eventinitsol)))
Definition: scip_event.c:183
enum SCIP_Retcode SCIP_RETCODE
Definition: type_retcode.h:54
type definitions for return codes for SCIP methods
SCIP_EXPORT SCIP_RETCODE SCIPsetEventhdlrCopy(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTCOPY((*eventcopy)))
Definition: scip_event.c:127
SCIP_DECL_EVENTINITSOL(EventhdlrNewSol::scip_initsol)
type definitions for LP management
SCIP_EXPORT SCIP_EVENTHDLR ** SCIPgetEventhdlrs(SCIP *scip)
Definition: scip_event.c:238
SCIP_DECL_EVENTINIT(EventhdlrNewSol::scip_init)
SCIP_DECL_EVENTFREE(EventhdlrNewSol::scip_free)
SCIP_EXPORT SCIP_RETCODE SCIPsetEventhdlrFree(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTFREE((*eventfree)))
Definition: scip_event.c:141
SCIP_EXPORT SCIP_RETCODE SCIPcatchEvent(SCIP *scip, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int *filterpos)
Definition: scip_event.c:277
type definitions for SCIP&#39;s main datastructure
struct SCIP_EventData SCIP_EVENTDATA
Definition: type_event.h:164
type definitions for problem variables
type definitions for managing events
SCIP_EXPORT SCIP_RETCODE SCIPdropVarEvent(SCIP *scip, SCIP_VAR *var, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int filterpos)
Definition: scip_event.c:391
SCIP_EXPORT SCIP_RETCODE SCIPcatchRowEvent(SCIP *scip, SCIP_ROW *row, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int *filterpos)
Definition: scip_event.c:431
SCIP_EXPORT SCIP_RETCODE SCIPsetEventhdlrExitsol(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTEXITSOL((*eventexitsol)))
Definition: scip_event.c:197
SCIP_EXPORT SCIP_RETCODE SCIPincludeEventhdlrBasic(SCIP *scip, SCIP_EVENTHDLR **eventhdlrptr, const char *name, const char *desc, SCIP_DECL_EVENTEXEC((*eventexec)), SCIP_EVENTHDLRDATA *eventhdlrdata)
Definition: scip_event.c:95
SCIP_EXPORT SCIP_RETCODE SCIPsetEventhdlrDelete(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTDELETE((*eventdelete)))
Definition: scip_event.c:211
SCIP_EXPORT SCIP_RETCODE SCIPsetEventhdlrInit(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTINIT((*eventinit)))
Definition: scip_event.c:155
SCIP_EXPORT SCIP_RETCODE SCIPdropEvent(SCIP *scip, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int filterpos)
Definition: scip_event.c:311
SCIP_EXPORT SCIP_RETCODE SCIPincludeEventhdlr(SCIP *scip, const char *name, const char *desc, SCIP_DECL_EVENTCOPY((*eventcopy)), SCIP_DECL_EVENTFREE((*eventfree)), SCIP_DECL_EVENTINIT((*eventinit)), SCIP_DECL_EVENTEXIT((*eventexit)), SCIP_DECL_EVENTINITSOL((*eventinitsol)), SCIP_DECL_EVENTEXITSOL((*eventexitsol)), SCIP_DECL_EVENTDELETE((*eventdelete)), SCIP_DECL_EVENTEXEC((*eventexec)), SCIP_EVENTHDLRDATA *eventhdlrdata)
Definition: scip_event.c:54
SCIP_DECL_EVENTEXEC(EventhdlrNewSol::scip_exec)
SCIP_DECL_EVENTEXITSOL(EventhdlrNewSol::scip_exitsol)
#define SCIP_DECL_EVENTCOPY(x)
Definition: type_event.h:174
SCIP_EXPORT SCIP_RETCODE SCIPcatchVarEvent(SCIP *scip, SCIP_VAR *var, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int *filterpos)
Definition: scip_event.c:345
SCIP_EXPORT SCIP_RETCODE SCIPdropRowEvent(SCIP *scip, SCIP_ROW *row, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int filterpos)
Definition: scip_event.c:471
SCIP_DECL_EVENTDELETE(EventhdlrNewSol::scip_delete)
common defines and data types used in all packages of SCIP
SCIP_EXPORT SCIP_RETCODE SCIPsetEventhdlrExit(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTEXIT((*eventexit)))
Definition: scip_event.c:169
uint64_t SCIP_EVENTTYPE
Definition: type_event.h:142