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