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   tpi.h
26   	 * @ingroup TASKINTERFACE
27   	 * @brief  the type definitions for the SCIP parallel interface
28   	 * @author Leona Gottwald
29   	 * @author Stephen J. Maher
30   	 * @author Marc Pfetsch
31   	 */
32   	
33   	/*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
34   	
35   	#ifndef __TPI_H__
36   	#define __TPI_H__
37   	
38   	#include "scip/def.h"
39   	#include "scip/type_retcode.h"
40   	#include "tpi/type_tpi.h"
41   	
42   	/** creates and initializes the given lock */
43   	SCIP_EXPORT
44   	SCIP_RETCODE SCIPtpiInitLock(
45   	   SCIP_LOCK**           lock                /**< the lock */
46   	   );
47   	
48   	/** destroys and frees the given lock */
49   	SCIP_EXPORT
50   	void SCIPtpiDestroyLock(
51   	   SCIP_LOCK**           lock                /**< the lock */
52   	   );
53   	
54   	/** acquires the given lock */
55   	SCIP_EXPORT
56   	SCIP_RETCODE SCIPtpiAcquireLock(
57   	   SCIP_LOCK*            lock                /**< the lock */
58   	   );
59   	
60   	/** releases the given lock */
61   	SCIP_EXPORT
62   	SCIP_RETCODE SCIPtpiReleaseLock(
63   	   SCIP_LOCK*            lock                /**< the lock */
64   	   );
65   	
66   	/** initializes the given condition variable */
67   	SCIP_EXPORT
68   	SCIP_RETCODE SCIPtpiInitCondition(
69   	   SCIP_CONDITION**      condition           /**< condition to be created and initialized */
70   	   );
71   	
72   	/** destroys the given condition variable */
73   	SCIP_EXPORT
74   	void SCIPtpiDestroyCondition(
75   	   SCIP_CONDITION**      condition           /**< condition to be destroyed and freed */
76   	   );
77   	
78   	/** signals one waiting thread */
79   	SCIP_EXPORT
80   	SCIP_RETCODE SCIPtpiSignalCondition(
81   	   SCIP_CONDITION*       condition           /**< the condition variable to signal */
82   	   );
83   	
84   	/** signals all waiting threads */
85   	SCIP_EXPORT
86   	SCIP_RETCODE SCIPtpiBroadcastCondition(
87   	   SCIP_CONDITION*       condition           /**< the condition variable to broadcast */
88   	   );
89   	
90   	/** waits on a condition variable. The given lock must be held by the caller and will
91   	 *  be held when this function returns.
92   	 */
93   	SCIP_EXPORT
94   	SCIP_RETCODE SCIPtpiWaitCondition(
95   	   SCIP_CONDITION*       condition,          /**< the condition variable to wait on */
96   	   SCIP_LOCK*            lock                /**< the lock that is held by the caller */
97   	   );
98   	
99   	/** returns the number of threads */
100  	SCIP_EXPORT
101  	int SCIPtpiGetNumThreads(
102  	   void
103  	   );
104  	
105  	/** returns the thread number */
106  	SCIP_EXPORT
107  	int SCIPtpiGetThreadNum(
108  	   void
109  	   );
110  	
111  	/** creates a job for parallel processing */
112  	SCIP_EXPORT
113  	SCIP_RETCODE SCIPtpiCreateJob(
114  	   SCIP_JOB**            job,                /**< pointer to the job that will be created */
115  	   int                   jobid,              /**< the id for the current job */
116  	   SCIP_RETCODE          (*jobfunc)(void* args),/**< pointer to the job function */
117  	   void*                 jobarg              /**< the job's argument */
118  	   );
119  	
120  	/** get a new job id for a new set of jobs */
121  	SCIP_EXPORT
122  	int SCIPtpiGetNewJobID(
123  	   void
124  	   );
125  	
126  	/** submit a job for parallel processing; the return value is a globally defined status */
127  	SCIP_EXPORT
128  	SCIP_RETCODE SCIPtpiSubmitJob(
129  	   SCIP_JOB*             job,                /**< pointer to the job to be submitted */
130  	   SCIP_SUBMITSTATUS*    status              /**< pointer to store the job's submit status */
131  	   );
132  	
133  	/** blocks until all jobs of the given jobid have finished
134  	 *  and then returns the smallest SCIP_RETCODE of all the jobs
135  	 */
136  	SCIP_EXPORT
137  	SCIP_RETCODE SCIPtpiCollectJobs(
138  	   int                   jobid               /**< the jobid of the jobs to wait for */
139  	   );
140  	
141  	/** initializes tpi */
142  	SCIP_EXPORT
143  	SCIP_RETCODE SCIPtpiInit(
144  	   int                   nthreads,           /**< the number of threads to be used */
145  	   int                   queuesize,          /**< the size of the queue */
146  	   /*TODO: specify and implement behaviour of blockwhenfull flag*/
147  	   SCIP_Bool             blockwhenfull       /**< should the queue block when full */
148  	   );
149  	
150  	/** deinitializes the tpi */
151  	SCIP_EXPORT
152  	SCIP_RETCODE SCIPtpiExit(
153  	   void
154  	   );
155  	
156  	#endif
157