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   syncstore.h
26   	 * @ingroup PARALLEL
27   	 * @brief  the function declarations for the synchronization store
28   	 * @author Leona Gottwald
29   	 * @author Stephen J. Maher
30   	 */
31   	
32   	/*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
33   	
34   	#ifndef __SYNCSTORE_H__
35   	#define __SYNCSTORE_H__
36   	
37   	#include "scip/def.h"
38   	#include "scip/type_syncstore.h"
39   	#include "scip/type_scip.h"
40   	#include "scip/type_retcode.h"
41   	
42   	/** creates and captures a new synchronization store */
43   	SCIP_EXPORT
44   	SCIP_RETCODE SCIPsyncstoreCreate(
45   	   SCIP_SYNCSTORE**      syncstore           /**< pointer to return the created synchronization store */
46   	   );
47   	
48   	/** releases a synchronization store */
49   	SCIP_EXPORT
50   	SCIP_RETCODE SCIPsyncstoreRelease(
51   	   SCIP_SYNCSTORE**      syncstore           /**< pointer to the synchronization store */
52   	   );
53   	
54   	/** captures a synchronization store */
55   	SCIP_EXPORT
56   	SCIP_RETCODE SCIPsyncstoreCapture(
57   	   SCIP_SYNCSTORE*       syncstore           /**< the synchronization store */
58   	   );
59   	
60   	/** initialize the syncstore for the given SCIP instance */
61   	SCIP_EXPORT
62   	SCIP_RETCODE SCIPsyncstoreInit(
63   	   SCIP*                 scip                /**< SCIP main datastructure */
64   	   );
65   	
66   	/** deinitializes the synchronization store */
67   	SCIP_EXPORT
68   	SCIP_RETCODE SCIPsyncstoreExit(
69   	   SCIP_SYNCSTORE*       syncstore           /**< the synchronization store */
70   	   );
71   	
72   	/** checks whether the solve-is-stopped flag in the syncstore has been set by any thread */
73   	SCIP_EXPORT
74   	SCIP_Bool SCIPsyncstoreSolveIsStopped(
75   	   SCIP_SYNCSTORE*       syncstore           /**< the synchronization store */
76   	   );
77   	
78   	/** sets the solve-is-stopped flag in the syncstore so that subsequent calls to
79   	 *  SCIPsyncstoreSolveIsStopped will return the given value in any thread
80   	 */
81   	SCIP_EXPORT
82   	void SCIPsyncstoreSetSolveIsStopped(
83   	   SCIP_SYNCSTORE*       syncstore,          /**< the synchronization store */
84   	   SCIP_Bool             stopped             /**< flag if the solve is stopped */
85   	   );
86   	
87   	/** gets the upperbound from the last synchronization */
88   	SCIP_EXPORT
89   	SCIP_Real SCIPsyncstoreGetLastUpperbound(
90   	   SCIP_SYNCSTORE*       syncstore           /**< the synchronization store */
91   	   );
92   	
93   	/** gets the lowerbound from the last synchronization */
94   	SCIP_EXPORT
95   	SCIP_Real SCIPsyncstoreGetLastLowerbound(
96   	   SCIP_SYNCSTORE*       syncstore           /**< the synchronization store */
97   	   );
98   	
99   	/** gets the number of solutions from the last synchronization */
100  	SCIP_EXPORT
101  	int SCIPsyncstoreGetLastNSols(
102  	   SCIP_SYNCSTORE*       syncstore           /**< the synchronization store */
103  	   );
104  	
105  	/** gets the number of boundchanges from the last synchronization */
106  	SCIP_EXPORT
107  	int SCIPsyncstoreGetLastNBounds(
108  	   SCIP_SYNCSTORE*       syncstore           /**< the synchronization store */
109  	   );
110  	
111  	/** gets total memory used by all solvers from the last synchronization */
112  	SCIP_EXPORT
113  	SCIP_Longint SCIPsyncstoreGetLastMemTotal(
114  	   SCIP_SYNCSTORE*       syncstore           /**< the synchronization store */
115  	   );
116  	
117  	/** gets the synchronization frequency from the last synchronization */
118  	SCIP_EXPORT
119  	SCIP_Real SCIPsyncstoreGetLastSyncfreq(
120  	   SCIP_SYNCSTORE*       syncstore           /**< the synchronization store */
121  	   );
122  	
123  	/** get synchronization data with given number. It is the responsibility of the caller
124  	 *  to only ask for a synchronization number that still exists. */
125  	SCIP_EXPORT
126  	SCIP_SYNCDATA* SCIPsyncstoreGetSyncdata(
127  	   SCIP_SYNCSTORE*       syncstore,          /**< the synchronization store */
128  	   SCIP_Longint          syncnum             /**< the number of the synchronization to start, which
129  	                                              *   must be increasing between calls of the same thread */
130  	   );
131  	
132  	/** get the next synchronization data that should be read and
133  	 *  adjust the delay. Returns NULL if no more data should be read due to minimum delay */
134  	SCIP_EXPORT
135  	SCIP_SYNCDATA* SCIPsyncstoreGetNextSyncdata(
136  	   SCIP_SYNCSTORE*       syncstore,          /**< the synchronization store */
137  	   SCIP_SYNCDATA*        syncdata,           /**< the synchronization data */
138  	   SCIP_Real             syncfreq,           /**< the current synchronization frequency */
139  	   SCIP_Longint          writenum,           /**< number of synchronizations the solver has written to */
140  	   SCIP_Real*            delay               /**< pointer holding the current synchronization delay */
141  	   );
142  	
143  	/** ensures that the given synchronization data has been written by
144  	 *  all solvers upon return of this function and blocks the caller if necessary. */
145  	SCIP_EXPORT
146  	SCIP_RETCODE SCIPsyncstoreEnsureAllSynced(
147  	   SCIP_SYNCSTORE*       syncstore,          /**< the synchronization store */
148  	   SCIP_SYNCDATA*        syncdata            /**< the synchronization data */
149  	   );
150  	
151  	/** Start synchronization for the given concurrent solver.
152  	 *  Needs to be followed by a call to SCIPsyncstoreFinishSync if
153  	 *  the syncdata that is returned is not NULL
154  	 */
155  	SCIP_EXPORT
156  	SCIP_RETCODE SCIPsyncstoreStartSync(
157  	   SCIP_SYNCSTORE*       syncstore,          /**< the synchronization store */
158  	   SCIP_Longint          syncnum,            /**< the number of the synchronization to start, which
159  	                                              *   must be increasing between calls of the same thread */
160  	   SCIP_SYNCDATA**       syncdata            /**< pointer to return the synchronization data */
161  	   );
162  	
163  	/** finishes synchronization for the synchronization data */
164  	SCIP_EXPORT
165  	SCIP_RETCODE SCIPsyncstoreFinishSync(
166  	   SCIP_SYNCSTORE*       syncstore,          /**< the synchronization store */
167  	   SCIP_SYNCDATA**       syncdata            /**< the synchronization data */
168  	   );
169  	
170  	/** gets status in synchronization data */
171  	SCIP_EXPORT
172  	SCIP_STATUS SCIPsyncdataGetStatus(
173  	   SCIP_SYNCDATA*        syncdata            /**< the synchronization data */
174  	   );
175  	
176  	/** gets the solver that had the best status, or -1 if solve is not stopped yet */
177  	SCIP_EXPORT
178  	int SCIPsyncstoreGetWinner(
179  	   SCIP_SYNCSTORE*       syncstore           /**< the synchronization store */
180  	   );
181  	
182  	/** how many solvers have already finished synchronizing on this sychronization data */
183  	SCIP_EXPORT
184  	int SCIPsyncdataGetNSynced(
185  	   SCIP_SYNCDATA*        syncdata            /**< the synchronization data */
186  	   );
187  	
188  	/** how many solvers have are running concurrently */
189  	SCIP_EXPORT
190  	int SCIPsyncstoreGetNSolvers(
191  	   SCIP_SYNCSTORE*       syncstore           /**< the synchronization store */
192  	   );
193  	
194  	/** read amount of memory used from synchronization data */
195  	SCIP_EXPORT
196  	SCIP_Longint SCIPsyncdataGetMemTotal(
197  	   SCIP_SYNCDATA*        syncdata            /**< the synchronization data */
198  	   );
199  	
200  	/** read the synchronization frequency from a synchronization data */
201  	SCIP_EXPORT
202  	SCIP_Real SCIPsyncdataGetSyncFreq(
203  	   SCIP_SYNCDATA*        syncdata            /**< the synchronization data */
204  	   );
205  	
206  	/** read the upperbound stored in a synchronization data */
207  	SCIP_EXPORT
208  	SCIP_Real SCIPsyncdataGetUpperbound(
209  	   SCIP_SYNCDATA*        syncdata            /**< the synchronization data */
210  	   );
211  	
212  	/** read the lowerbound stored in a synchronization data */
213  	SCIP_EXPORT
214  	SCIP_Real SCIPsyncdataGetLowerbound(
215  	   SCIP_SYNCDATA*        syncdata            /**< the synchronization data */
216  	   );
217  	
218  	/** read the solutions stored in a synchronization data */
219  	SCIP_EXPORT
220  	void SCIPsyncdataGetSolutions(
221  	   SCIP_SYNCDATA*        syncdata,           /**< the synchronization data */
222  	   SCIP_Real***          solvalues,          /**< pointer to return array of buffers containing the solution values */
223  	   int**                 solowner,           /**< pointer to return array of ownerids of solutions */
224  	   int*                  nsols               /**< pointer to return number of solutions */
225  	   );
226  	
227  	/** read bound changes stored in the synchronization data */
228  	SCIP_EXPORT
229  	SCIP_BOUNDSTORE* SCIPsyncdataGetBoundChgs(
230  	   SCIP_SYNCDATA*        syncdata            /**< the synchronization data */
231  	   );
232  	
233  	/** write the synchronization frequency to a synchronization data */
234  	SCIP_EXPORT
235  	void SCIPsyncdataSetSyncFreq(
236  	   SCIP_SYNCSTORE*       syncstore,          /**< the synchronization store */
237  	   SCIP_SYNCDATA*        syncdata,           /**< the synchronization data */
238  	   SCIP_Real             syncfreq            /**< the synchronization frequency */
239  	   );
240  	
241  	/** set status in the synchronization data */
242  	SCIP_EXPORT
243  	void SCIPsyncdataSetStatus(
244  	   SCIP_SYNCDATA*        syncdata,           /**< the synchronization data the upperbound should be added to */
245  	   SCIP_STATUS           status,             /**< the status */
246  	   int                   solverid            /**< identifier of te solver that has this status */
247  	   );
248  	
249  	/** adds memory used to the synchronization data */
250  	SCIP_EXPORT
251  	void SCIPsyncdataAddMemTotal(
252  	   SCIP_SYNCDATA*        syncdata,           /**< the synchronization data the solution should be added to */
253  	   SCIP_Longint          memtotal            /**< the number of bytes used */
254  	   );
255  	
256  	/** set upperbound to the synchronization data */
257  	SCIP_EXPORT
258  	void SCIPsyncdataSetUpperbound(
259  	   SCIP_SYNCDATA*        syncdata,           /**< the synchronization data the upperbound should be added to */
260  	   SCIP_Real             upperbound          /**< the upperbound */
261  	   );
262  	
263  	/** set lowerbound to the synchronization data */
264  	SCIP_EXPORT
265  	void SCIPsyncdataSetLowerbound(
266  	   SCIP_SYNCDATA*        syncdata,           /**< the synchronization data the lowerbound should be added to */
267  	   SCIP_Real             lowerbound          /**< the lowerbound */
268  	   );
269  	
270  	/** gives a buffer to store the solution values, or NULL if solution should not be stored
271  	 *  because there are already better solutions stored.
272  	 */
273  	SCIP_EXPORT
274  	void SCIPsyncdataGetSolutionBuffer(
275  	   SCIP_SYNCSTORE*       syncstore,          /**< the synchronization store */
276  	   SCIP_SYNCDATA*        syncdata,           /**< the synchronization data the solution should be added to */
277  	   SCIP_Real             solobj,             /**< the objective value of the solution */
278  	   int                   ownerid,            /**< an identifier for the owner of the solution, e.g. the thread number */
279  	   SCIP_Real**           buffer              /**< pointer to return a buffer for the solution values, which must be set
280  	                                              *   if the buffer is not NULL */
281  	   );
282  	
283  	/** adds bound changes to the synchronization data */
284  	SCIP_EXPORT
285  	SCIP_RETCODE SCIPsyncdataAddBoundChanges(
286  	   SCIP_SYNCSTORE*       syncstore,          /**< the synchronization store */
287  	   SCIP_SYNCDATA*        syncdata,           /**< the synchronization data */
288  	   SCIP_BOUNDSTORE*      boundstore          /**< bound store containing the bounds to add */
289  	   );
290  	
291  	/** is synchronization store initialized */
292  	SCIP_EXPORT
293  	SCIP_Bool SCIPsyncstoreIsInitialized(
294  	   SCIP_SYNCSTORE*       syncstore           /**< the synchronization store */
295  	   );
296  	
297  	/** returns the mode of the synchronization store */
298  	SCIP_EXPORT
299  	SCIP_PARALLELMODE SCIPsyncstoreGetMode(
300  	   SCIP_SYNCSTORE*       syncstore           /**< the synchronization store */
301  	   );
302  	
303  	#endif
304