rpm  5.4.15
yarn.h
Go to the documentation of this file.
1 /* yarn.h -- generic interface for thread operations
2  * Copyright (C) 2008 Mark Adler
3  * Version 1.1 26 Oct 2008 Mark Adler
4  */
5 #ifndef _H_YARN_
6 #define _H_YARN_
7 
8 /*
9  This software is provided 'as-is', without any express or implied
10  warranty. In no event will the author be held liable for any damages
11  arising from the use of this software.
12 
13  Permission is granted to anyone to use this software for any purpose,
14  including commercial applications, and to alter it and redistribute it
15  freely, subject to the following restrictions:
16 
17  1. The origin of this software must not be misrepresented; you must not
18  claim that you wrote the original software. If you use this software
19  in a product, an acknowledgment in the product documentation would be
20  appreciated but is not required.
21  2. Altered source versions must be plainly marked as such, and must not be
22  misrepresented as being the original software.
23  3. This notice may not be removed or altered from any source distribution.
24 
25  Mark Adler
26  madler@alumni.caltech.edu
27  */
28 
29 /* Basic thread operations
30 
31  This interface isolates the local operating system implementation of threads
32  from the application in order to facilitate platform independent use of
33  threads. All of the implementation details are deliberately hidden.
34 
35  Assuming adequate system resources and proper use, none of these functions
36  can fail. As a result, any errors encountered will cause an exit() to be
37  executed.
38 
39  These functions allow the simple launching and joining of threads, and the
40  locking of objects and synchronization of changes of objects. The latter is
41  implemented with a single lock type that contains an integer value. The
42  value can be ignored for simple exclusive access to an object, or the value
43  can be used to signal and wait for changes to an object.
44 
45  -- Arguments --
46 
47  thread *thread; identifier for launched thread, used by join
48  void probe(void *); pointer to function "probe", run when thread starts
49  void *payload; single argument passed to the probe function
50  yarnLock lock; a lock with a value -- used for exclusive access to
51  an object and to synchronize threads waiting for
52  changes to an object
53  long val; value to set lock, increment lock, or wait for
54  int n; number of threads joined
55 
56  -- Thread functions --
57 
58  thread = yarnLaunch(probe, payload) - launch a thread -- exit via probe() return
59  yarnJoin(thread) - join a thread and by joining end it, waiting for the thread
60  to exit if it hasn't already -- will free the resources allocated by
61  yarnLaunch() (don't try to join the same thread more than once)
62  n = yarnJoinAll() - join all threads launched by yarnLaunch() that are not joined
63  yet and free the resources allocated by the launches, usually to clean
64  up when the thread processing is done -- yarnJoinAll() returns an int with
65  the count of the number of threads joined (yarnJoinAll() should only be
66  called from the main thread, and should only be called after any calls
67  of yarnJoin() have completed)
68  yarnDestruct(thread) - terminate the thread in mid-execution and join it
69  (depending on the implementation, the termination may not be immediate,
70  but may wait for the thread to execute certain thread or file i/o
71  operations)
72 
73  -- Lock functions --
74 
75  lock = yarnNewLock(val) - create a new lock with initial value val (lock is
76  created in the released state)
77  yarnPossess(lock) - acquire exclusive possession of a lock, waiting if necessary
78  yarnTwist(lock, [TO | BY], val) - set lock to or increment lock by val, signal
79  all threads waiting on this lock and then release the lock -- must
80  possess the lock before calling (twist releases, so don't do a
81  yarnRelease() after a yarnTwist() on the same lock)
82  yarnWaitFor(lock, [TO_BE | NOT_TO_BE | TO_BE_MORE_THAN | TO_BE_LESS_THAN], val)
83  - wait on lock value to be, not to be, be greater than, or be less than
84  val -- must possess the lock before calling, will possess the lock on
85  return but the lock is released while waiting to permit other threads
86  to use yarnTwist() to change the value and signal the change (so make sure
87  that the object is in a usable state when waiting)
88  yarnRelease(lock) - release a possessed lock (do not try to release a lock that
89  the current thread does not possess)
90  val = yarnPeekLock(lock) - return the value of the lock (assumes that lock is
91  already possessed, no possess or release is done by yarnPeekLock())
92  yarnFreeLock(lock) - free the resources allocated by yarnNewLock() (application
93  must assure that the lock is released before calling yarnFreeLock())
94 
95  -- Memory allocation ---
96 
97  yarnMem(better_malloc, better_free) - set the memory allocation and free
98  routines for use by the yarn routines where the supplied routines have
99  the same interface and operation as malloc() and free(), and may be
100  provided in order to supply thread-safe memory allocation routines or
101  for any other reason -- by default malloc() and free() will be used
102 
103  -- Error control --
104 
105  yarnPrefix - a char pointer to a string that will be the prefix for any error
106  messages that these routines generate before exiting -- if not changed
107  by the application, "yarn" will be used
108  yarnAbort - an external function that will be executed when there is an
109  internal yarn error, due to out of memory or misuse -- this function
110  may exit to abort the application, or if it returns, the yarn error
111  handler will exit (set to NULL by default for no action)
112  */
113 
114 #include <sys/types.h> /* XXX size_t typedef */
115 #include <rpmiotypes.h> /* XXX yarnLock typedef */
116 
117 #ifdef __cplusplus
118 extern "C" {
119 #endif
120 
121 /*@unchecked@*/ /*@observer@*/
122 extern const char *yarnPrefix;
123 /*@-redecl@*/
124 /*@mayexit@*/
125 extern void (*yarnAbort)(int)
126  /*@globals internalState @*/
127  /*@modifies internalState @*/;
128 /*@=redecl@*/
129 
130 /*@-globuse@*/
131 void yarnMem(void *(*)(size_t), void (*)(void *))
132  /*@globals internalState @*/
133  /*@modifies internalState @*/;
134 /*@=globuse@*/
135 
136 typedef struct yarnThread_s * yarnThread;
137 /*@only@*/
138 yarnThread yarnLaunchStack(void (*probe)(void *), void *payload,
139  /*@null@*/ void * stack, size_t nstack)
140  /*@globals fileSystem, internalState @*/
141  /*@modifies fileSystem, internalState @*/;
142 /*@only@*/
143 yarnThread yarnLaunch(void (*probe)(void *), void *payload)
144  /*@globals fileSystem, internalState @*/
145  /*@modifies fileSystem, internalState @*/;
146 /*@only@*/ /*@null@*/
147 yarnThread yarnJoin(/*@only@*/ yarnThread ally)
148  /*@globals fileSystem, internalState @*/
149  /*@modifies ally, fileSystem, internalState @*/;
150 int yarnJoinAll(void)
151  /*@globals fileSystem, internalState @*/
152  /*@modifies fileSystem, internalState @*/;
153 void yarnDestruct(/*@only@*/ yarnThread off_course)
154  /*@globals fileSystem, internalState @*/
155  /*@modifies off_course, fileSystem, internalState @*/;
156 
157 yarnLock yarnNewLock(long)
158  /*@globals fileSystem, internalState @*/
159  /*@modifies fileSystem, internalState @*/;
160 void yarnPossess(yarnLock bolt)
161  /*@globals fileSystem, internalState @*/
162  /*@modifies bolt, fileSystem, internalState @*/;
163 void yarnRelease(yarnLock bolt)
164  /*@globals fileSystem, internalState @*/
165  /*@modifies bolt, fileSystem, internalState @*/;
166 typedef enum yarnTwistOP_e { TO, BY } yarnTwistOP;
167 void yarnTwist(yarnLock bolt, yarnTwistOP op, long)
168  /*@globals fileSystem, internalState @*/
169  /*@modifies bolt, fileSystem, internalState @*/;
170 typedef enum yarnWaitOP_e {
171  TO_BE, /* or */ NOT_TO_BE, /* that is the question */
173 void yarnWaitFor(yarnLock bolt, yarnWaitOP op, long)
174  /*@globals fileSystem, internalState @*/
175  /*@modifies bolt, fileSystem, internalState @*/;
176 long yarnPeekLock(yarnLock bolt)
177  /*@*/;
178 /*@only@*/ /*@null@*/
179 yarnLock yarnFreeLock(/*@only@*/ yarnLock bolt)
180  /*@globals fileSystem, internalState @*/
181  /*@modifies bolt, fileSystem, internalState @*/;
182 
183 #ifdef __cplusplus
184 }
185 #endif
186 
187 #endif /* _H_YARN_ */
void yarnWaitFor(yarnLock bolt, yarnWaitOP op, long)
Definition: yarn.c:295
enum yarnTwistOP_e yarnTwistOP
void yarnDestruct(yarnThread off_course)
Definition: yarn.c:571
yarnLock yarnNewLock(long)
Definition: yarn.c:248
Definition: yarn.h:171
void yarnTwist(yarnLock bolt, yarnTwistOP op, long)
Definition: yarn.c:279
Definition: yarn.h:166
long yarnPeekLock(yarnLock bolt)
Definition: yarn.c:325
yarnWaitOP_e
Definition: yarn.h:170
struct yarnThread_s * yarnThread
Definition: yarn.h:136
const char * yarnPrefix
Definition: yarn.c:180
yarnThread yarnJoin(yarnThread ally)
Definition: yarn.c:488
enum yarnWaitOP_e yarnWaitOP
yarnThread yarnLaunchStack(void(*probe)(void *), void *payload, void *stack, size_t nstack)
Definition: yarn.c:436
const char const bson const bson * op
Definition: mongo.h:505
void yarnRelease(yarnLock bolt)
Definition: yarn.c:270
void yarnMem(void *(*)(size_t), void(*)(void *))
void yarnPossess(yarnLock bolt)
Definition: yarn.c:262
yarnThread yarnLaunch(void(*probe)(void *), void *payload)
Definition: yarn.c:481
Definition: yarn.h:166
int yarnJoinAll(void)
Definition: yarn.c:524
yarnTwistOP_e
Definition: yarn.h:166
yarnLock yarnFreeLock(yarnLock bolt)
Definition: yarn.c:330
void(* yarnAbort)(int)
Definition: yarn.c:182