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