coregrind/pub_core_scheduler.h

   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-2017 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, see <http://www.gnu.org/licenses/>.
  25
  26    The GNU General Public License is contained in the file COPYING.
  27 */
  28
  29 #ifndef __PUB_CORE_SCHEDULER_H
  30 #define __PUB_CORE_SCHEDULER_H
  31
  32 #include "pub_core_basics.h"        // VG_ macro
  33 #include "pub_core_threadstate.h"   // VgSchedReturnCode
  34
  35 //--------------------------------------------------------------------
  36 // PURPOSE: This module is the scheduler, which is the main loop
  37 // controlling the running of all the program's threads.
  38 // It's at the centre of everything.
  39 //--------------------------------------------------------------------
  40
  41 /* Allocate a new ThreadState */
  42 extern ThreadId VG_(alloc_ThreadState)(void);
  43
  44 /* A thread exits.  tid must currently be running. */
  45 extern void VG_(exit_thread)(ThreadId tid);
  46
  47 /* If 'tid' is blocked in a syscall, send it SIGVGKILL so as to get it
  48    out of the syscall and onto doing the next thing, whatever that is.
  49    If it isn't blocked in a syscall, has no effect on the thread. */
  50 extern void VG_(get_thread_out_of_syscall)(ThreadId tid);
  51
  52 /* This causes all threads except tid to forceably exit.  They aren't actually
  53    dead by the time this returns; you need to call
  54    VG_(reap_threads)() to wait for them. */
  55 extern 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. */
  63 extern 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. */
  68 extern 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. */
  78 extern void VG_(release_BigLock) ( ThreadId tid,
  79                                    ThreadStatus state, const HChar* who );
  80
  81 /* Matching function to acquire_BigLock_LL. */
  82 extern void VG_(release_BigLock_LL) ( const HChar* who );
  83
  84 /* Whether the specified thread owns the big lock. */
  85 extern 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. */
  89 extern void VG_(vg_yield)(void);
  90
  91 // The scheduler.
  92 extern VgSchedReturnCode VG_(scheduler) ( ThreadId tid );
  93
  94 // Initialise, phase 1.  Zero out VG_(threads), decide on the root
  95 // ThreadId and initialise the bigLock.
  96 extern ThreadId VG_(scheduler_init_phase1) ( void );
  97
  98 // Initialise, phase 2.  Is passed the extent of the root thread's
  99 // client stack end (highest addressable byte) and the root ThreadId
 100 // decided on by phase 1.
 101 extern void VG_(scheduler_init_phase2) ( ThreadId main_tid,
 102                                          Addr     clstack_end,
 103                                          SizeT    clstack_size );
 104
 105 // Allows to disable the polling done to detect vgdb input
 106 // or to force a poll at next scheduler call.
 107 extern void VG_(disable_vgdb_poll) (void );
 108 extern void VG_(force_vgdb_poll) ( void );
 109
 110 /* Stats ... */
 111 extern void VG_(print_scheduler_stats) ( void );
 112
 113 /* If False, a fault is Valgrind-internal (ie, a bug) */
 114 extern Bool VG_(in_generated_code);
 115
 116 /* Sanity checks which may be done at any time.  The scheduler decides when. */
 117 extern void VG_(sanity_check_general) ( Bool force_expensive );
 118
 119 #endif   // __PUB_CORE_SCHEDULER_H
 120
 121 /*--------------------------------------------------------------------*/
 122 /*--- end                                                          ---*/
 123 /*--------------------------------------------------------------------*/