1
2/*--------------------------------------------------------------------*/
3/*--- The scheduler.                          pub_core_scheduler.h ---*/
4/*--------------------------------------------------------------------*/
5
6/*
7   This file is part of Valgrind, a dynamic binary instrumentation
8   framework.
9
10   Copyright (C) 2000-2013 Julian Seward
11      jseward@acm.org
12
13   This program is free software; you can redistribute it and/or
14   modify it under the terms of the GNU General Public License as
15   published by the Free Software Foundation; either version 2 of the
16   License, or (at your option) any later version.
17
18   This program is distributed in the hope that it will be useful, but
19   WITHOUT ANY WARRANTY; without even the implied warranty of
20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
21   General Public License for more details.
22
23   You should have received a copy of the GNU General Public License
24   along with this program; if not, write to the Free Software
25   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
26   02111-1307, USA.
27
28   The GNU General Public License is contained in the file COPYING.
29*/
30
31#ifndef __PUB_CORE_SCHEDULER_H
32#define __PUB_CORE_SCHEDULER_H
33
34#include "pub_core_basics.h"        // VG_ macro
35#include "pub_core_threadstate.h"   // VgSchedReturnCode
36
37//--------------------------------------------------------------------
38// PURPOSE: This module is the scheduler, which is the main loop
39// controlling the running of all the program's threads.
40// It's at the centre of everything.
41//--------------------------------------------------------------------
42
43/* Allocate a new ThreadState */
44extern ThreadId VG_(alloc_ThreadState)(void);
45
46/* A thread exits.  tid must currently be running. */
47extern void VG_(exit_thread)(ThreadId tid);
48
49/* If 'tid' is blocked in a syscall, send it SIGVGKILL so as to get it
50   out of the syscall and onto doing the next thing, whatever that is.
51   If it isn't blocked in a syscall, has no effect on the thread. */
52extern void VG_(get_thread_out_of_syscall)(ThreadId tid);
53
54/* Nuke all threads except tid. */
55extern void VG_(nuke_all_threads_except) ( ThreadId me,
56                                           VgSchedReturnCode reason );
57
58/* Make a thread the running thread.  The thread must previously been
59   sleeping, and not holding the CPU lock.  This will set the
60   thread state to VgTs_Runnable, and the thread will attempt to take
61   the CPU lock.  By the time it returns, tid will be the running
62   thread. */
63extern void VG_(acquire_BigLock) ( ThreadId tid, const HChar* who );
64
65/* Simple version, which simply acquires the lock, but does not mess
66   with the guest state in the same way as the non _LL version
67   does. */
68extern void VG_(acquire_BigLock_LL) ( const HChar* who );
69
70/* Set a thread into a sleeping state.  Before the call, the thread
71   must be runnable, and holding the CPU lock.  When this call
72   returns, the thread will be set to the specified sleeping state,
73   and will not be holding the CPU lock.  Note that another
74   thread could be running by the time this call returns, so the
75   caller must be careful not to touch any shared state.  It is also
76   the caller's responsibility to actually block until the thread is
77   ready to run again. */
78extern void VG_(release_BigLock) ( ThreadId tid,
79                                   ThreadStatus state, const HChar* who );
80
81/* Matching function to acquire_BigLock_LL. */
82extern void VG_(release_BigLock_LL) ( const HChar* who );
83
84/* Whether the specified thread owns the big lock. */
85extern Bool VG_(owns_BigLock_LL) ( ThreadId tid );
86
87/* Yield the CPU for a while.  Drops/acquires the lock using the
88   normal (non _LL) functions. */
89extern void VG_(vg_yield)(void);
90
91// The scheduler.
92extern VgSchedReturnCode VG_(scheduler) ( ThreadId tid );
93
94// Initialise, phase 1.  Zero out VG_(threads), decide on the root
95// ThreadId and initialise the bigLock.
96extern ThreadId VG_(scheduler_init_phase1) ( void );
97
98// Initialise, phase 2.  Is passed the extent of the root thread's
99// client stack and the root ThreadId decided on by phase 1.
100extern void VG_(scheduler_init_phase2) ( ThreadId main_tid,
101                                         Addr     clstack_end,
102                                         SizeT    clstack_size );
103
104// Allows to disable the polling done to detect vgdb input
105// or to force a poll at next scheduler call.
106extern void VG_(disable_vgdb_poll) (void );
107extern void VG_(force_vgdb_poll) ( void );
108
109/* Stats ... */
110extern void VG_(print_scheduler_stats) ( void );
111
112/* If False, a fault is Valgrind-internal (ie, a bug) */
113extern Bool VG_(in_generated_code);
114
115/* Sanity checks which may be done at any time.  The scheduler decides when. */
116extern void VG_(sanity_check_general) ( Bool force_expensive );
117
118#endif   // __PUB_CORE_SCHEDULER_H
119
120/*--------------------------------------------------------------------*/
121/*--- end                                                          ---*/
122/*--------------------------------------------------------------------*/
123