Capability.h 8.84 KB
Newer Older
sof's avatar
sof committed
1
2
/* ---------------------------------------------------------------------------
 *
3
 * (c) The GHC Team, 2001-2006
sof's avatar
sof committed
4
5
6
7
 *
 * Capabilities
 *
 * The notion of a capability is used when operating in multi-threaded
8
 * environments (which the THREADED_RTS build of the RTS does), to
sof's avatar
sof committed
9
10
11
12
13
 * hold all the state an OS thread/task needs to run Haskell code:
 * its STG registers, a pointer to its  TSO, a nursery etc. During
 * STG execution, a pointer to the capabilitity is kept in a 
 * register (BaseReg).
 *
14
15
16
 * Only in an THREADED_RTS build will there be multiple capabilities,
 * in the non-threaded builds there is one global capability, namely
 * MainCapability.
sof's avatar
sof committed
17
18
19
20
21
 *
 * This header file contains the functions for working with capabilities.
 * (the main, and only, consumer of this interface is the scheduler).
 * 
 * --------------------------------------------------------------------------*/
22

23
24
#ifndef CAPABILITY_H
#define CAPABILITY_H
sof's avatar
sof committed
25

26
#include "RtsFlags.h"
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
#include "Task.h"

struct Capability_ {
    // State required by the STG virtual machine when running Haskell
    // code.  During STG execution, the BaseReg register always points
    // to the StgRegTable of the current Capability (&cap->r).
    StgFunTable f;
    StgRegTable r;

    nat no;  // capability number.

    // The Task currently holding this Capability.  This task has
    // exclusive access to the contents of this Capability (apart from
    // returning_tasks_hd/returning_tasks_tl).
    // Locks required: cap->lock.
    Task *running_task;

    // true if this Capability is running Haskell code, used for
    // catching unsafe call-ins.
    rtsBool in_haskell;

    // The run queue.  The Task owning this Capability has exclusive
    // access to its run queue, so can wake up threads without
    // taking a lock, and the common path through the scheduler is
    // also lock-free.
    StgTSO *run_queue_hd;
    StgTSO *run_queue_tl;

    // Tasks currently making safe foreign calls.  Doubly-linked.
    // When returning, a task first acquires the Capability before
    // removing itself from this list, so that the GC can find all
    // the suspended TSOs easily.  Hence, when migrating a Task from
    // the returning_tasks list, we must also migrate its entry from
    // this list.
    Task *suspended_ccalling_tasks;

63
64
65
66
67
68
    // One mutable list per generation, so we don't need to take any
    // locks when updating an old-generation thunk.  These
    // mini-mut-lists are moved onto the respective gen->mut_list at
    // each GC.
    bdescr **mut_lists;

69
70
71
72
#if defined(THREADED_RTS)
    // Worker Tasks waiting in the wings.  Singly-linked.
    Task *spare_workers;

73
    // This lock protects running_task, returning_tasks_{hd,tl}, wakeup_queue.
74
75
76
77
78
79
80
81
82
    Mutex lock;

    // Tasks waiting to return from a foreign call, or waiting to make
    // a new call-in using this Capability (NULL if empty).
    // NB. this field needs to be modified by tasks other than the
    // running_task, so it requires cap->lock to modify.  A task can
    // check whether it is NULL without taking the lock, however.
    Task *returning_tasks_hd; // Singly-linked, with head/tail
    Task *returning_tasks_tl;
83
84
85
86
87
88

    // A list of threads to append to this Capability's run queue at
    // the earliest opportunity.  These are threads that have been
    // woken up by another Capability.
    StgTSO *wakeup_queue_hd;
    StgTSO *wakeup_queue_tl;
89
#endif
90
91

    // Per-capability STM-related data
tharris@microsoft.com's avatar
tharris@microsoft.com committed
92
93
    StgTVarWatchQueue *free_tvar_watch_queues;
    StgInvariantCheckQueue *free_invariant_check_queues;
94
95
96
    StgTRecChunk *free_trec_chunks;
    StgTRecHeader *free_trec_headers;
    nat transaction_tokens;
97
}; // typedef Capability, defined in RtsAPI.h
98

99

sof's avatar
sof committed
100
101
102
103
104
105
#if defined(THREADED_RTS)
#define ASSERT_TASK_ID(task) ASSERT(task->id == osThreadId())
#else
#define ASSERT_TASK_ID(task) /*empty*/
#endif

106
// These properties should be true when a Task is holding a Capability
107
#define ASSERT_FULL_CAPABILITY_INVARIANTS(cap,task)			\
108
109
  ASSERT(cap->running_task != NULL && cap->running_task == task);	\
  ASSERT(task->cap == cap);						\
110
111
112
113
114
115
116
117
118
119
120
  ASSERT_PARTIAL_CAPABILITY_INVARIANTS(cap,task)

// Sometimes a Task holds a Capability, but the Task is not associated
// with that Capability (ie. task->cap != cap).  This happens when
// (a) a Task holds multiple Capabilities, and (b) when the current
// Task is bound, its thread has just blocked, and it may have been
// moved to another Capability.
#define ASSERT_PARTIAL_CAPABILITY_INVARIANTS(cap,task)	\
  ASSERT(cap->run_queue_hd == END_TSO_QUEUE ?		\
	    cap->run_queue_tl == END_TSO_QUEUE : 1);	\
  ASSERT(myTask() == task);				\
sof's avatar
sof committed
121
  ASSERT_TASK_ID(task);
122

123
124
125
126
127
128
129
// Converts a *StgRegTable into a *Capability.
//
INLINE_HEADER Capability *
regTableToCapability (StgRegTable *reg)
{
    return (Capability *)((void *)((unsigned char*)reg - sizeof(StgFunTable)));
}
130

131
// Initialise the available capabilities.
132
//
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
void initCapabilities (void);

// Release a capability.  This is called by a Task that is exiting
// Haskell to make a foreign call, or in various other cases when we
// want to relinquish a Capability that we currently hold.
//
// ASSUMES: cap->running_task is the current Task.
//
#if defined(THREADED_RTS)
void releaseCapability  (Capability* cap);
void releaseCapability_ (Capability* cap); // assumes cap->lock is held
#else
// releaseCapability() is empty in non-threaded RTS
INLINE_HEADER void releaseCapability  (Capability* cap STG_UNUSED) {};
INLINE_HEADER void releaseCapability_ (Capability* cap STG_UNUSED) {};
#endif
149

150
151
#if !IN_STG_CODE
// one global capability
152
153
154
155
extern Capability MainCapability; 
#endif

// Array of all the capabilities
156
//
157
158
extern nat n_capabilities;
extern Capability *capabilities;
159

160
161
// The Capability that was last free.  Used as a good guess for where
// to assign new threads.
162
//
163
extern Capability *last_free_capability;
164

165
166
167
168
169
170
171
172
173
174
// Acquires a capability at a return point.  If *cap is non-NULL, then
// this is taken as a preference for the Capability we wish to
// acquire.
//
// OS threads waiting in this function get priority over those waiting
// in waitForCapability().
//
// On return, *cap is non-NULL, and points to the Capability acquired.
//
void waitForReturnCapability (Capability **cap/*in/out*/, Task *task);
175

176
177
INLINE_HEADER void recordMutableCap (StgClosure *p, Capability *cap, nat gen);

178
#if defined(THREADED_RTS)
179

180
181
182
183
184
185
186
187
188
// Gives up the current capability IFF there is a higher-priority
// thread waiting for it.  This happens in one of two ways:
//
//   (a) we are passing the capability to another OS thread, so
//       that it can run a bound Haskell thread, or
//
//   (b) there is an OS thread waiting to return from a foreign call
//
// On return: *pCap is NULL if the capability was released.  The
189
// current task should then re-acquire it using waitForCapability().
190
//
191
void yieldCapability (Capability** pCap, Task *task);
192
193
194
195
196

// Acquires a capability for doing some work.
//
// On return: pCap points to the capability.
//
197
void waitForCapability (Task *task, Mutex *mutex, Capability **pCap);
198

199
200
201
202
// Wakes up a thread on a Capability (probably a different Capability
// from the one held by the current Task).
//
void wakeupThreadOnCapability (Capability *cap, StgTSO *tso);
203
204
205
206
void wakeupThreadOnCapability_lock (Capability *cap, StgTSO *tso);

void migrateThreadToCapability (Capability *cap, StgTSO *tso);
void migrateThreadToCapability_lock (Capability *cap, StgTSO *tso);
207

208
209
// Wakes up a worker thread on just one Capability, used when we
// need to service some global event.
210
//
211
void prodOneCapability (void);
212

213
// Similar to prodOneCapability(), but prods all of them.
214
//
215
void prodAllCapabilities (void);
sof's avatar
sof committed
216

217
218
219
// Waits for a capability to drain of runnable threads and workers,
// and then acquires it.  Used at shutdown time.
//
220
void shutdownCapability (Capability *cap, Task *task, rtsBool wait_foreign);
sof's avatar
sof committed
221

222
223
224
225
// Attempt to gain control of a Capability if it is free.
//
rtsBool tryGrabCapability (Capability *cap, Task *task);

226
#else // !THREADED_RTS
227
228
229
230

// Grab a capability.  (Only in the non-threaded RTS; in the threaded
// RTS one of the waitFor*Capability() functions must be used).
//
231
extern void grabCapability (Capability **pCap);
232

233
#endif /* !THREADED_RTS */
sof's avatar
sof committed
234

Ian Lynagh's avatar
Ian Lynagh committed
235
236
237
// Free a capability on exit
void freeCapability (Capability *cap);

238
239
240
// FOr the GC:
void markSomeCapabilities (evac_fn evac, void *user, nat i0, nat delta);
void markCapabilities (evac_fn evac, void *user);
241
242
void updateCapabilitiesPostGC (void);
void traverseSparkQueues (evac_fn evac, void *user);
243

244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
/* -----------------------------------------------------------------------------
 * INLINE functions... private below here
 * -------------------------------------------------------------------------- */

INLINE_HEADER void
recordMutableCap (StgClosure *p, Capability *cap, nat gen)
{
    bdescr *bd;

    bd = cap->mut_lists[gen];
    if (bd->free >= bd->start + BLOCK_SIZE_W) {
	bdescr *new_bd;
	new_bd = allocBlock_lock();
	new_bd->link = bd;
	bd = new_bd;
	cap->mut_lists[gen] = bd;
    }
    *bd->free++ = (StgWord)p;
}

264
#endif /* CAPABILITY_H */