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