src/rt/rust_kernel.h

   1 // Copyright 2012 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11
  12 /**
  13    A single runtime instance.
  14
  15    The kernel is primarily responsible for managing the lifetime of
  16    schedulers, which in turn run rust tasks. It provides a memory
  17    allocator and logging service for use by other runtime components,
  18    it creates unique task ids.
  19
  20    The kernel runs until there are no live schedulers.
  21
  22    The kernel internally runs an additional, special scheduler called
  23    the 'osmain' (or platform) scheduler, which schedules tasks on the
  24    thread that is running the kernel (normally the thread on which the
  25    C main function was called). This scheduler may be used by Rust
  26    code for interacting with platform APIs that insist on being called
  27    from the main thread.
  28
  29    The requirements of the osmain scheduler has resulted in a complex
  30    process for creating and running scheduler loops that involves
  31    a thing called a 'rust_sched_launcher_factory' whose function I've
  32    already forgotten. rust_scheduler is the main scheduler class,
  33    and tasks are scheduled on individual threads by rust_sched_loop.
  34
  35    Ideally all the in-memory Rust state is encapsulated by a kernel
  36    instance, but there is still some truly global data in the runtime
  37    (like the check claims flag).
  38  */
  39
  40 #ifndef RUST_KERNEL_H
  41 #define RUST_KERNEL_H
  42
  43 #include "rust_globals.h"
  44
  45 #include <map>
  46 #include <vector>
  47
  48 #include "rust_exchange_alloc.h"
  49 #include "rust_log.h"
  50 #include "rust_sched_reaper.h"
  51 #include "rust_type.h"
  52 #include "sync/lock_and_signal.h"
  53
  54 class rust_scheduler;
  55 class rust_sched_driver;
  56 class rust_sched_launcher_factory;
  57 struct rust_task_thread;
  58
  59 // Scheduler, task handles. These uniquely identify within a
  60 // single kernel instance the objects they represent.
  61 typedef intptr_t rust_sched_id;
  62 typedef intptr_t rust_task_id;
  63
  64 typedef std::map<rust_sched_id, rust_scheduler*> sched_map;
  65
  66 class rust_kernel {
  67     rust_exchange_alloc exchange_alloc;
  68     rust_log _log;
  69
  70     // The next task id
  71     rust_task_id max_task_id;
  72
  73     lock_and_signal rval_lock;
  74     int rval;
  75
  76     // Protects max_sched_id and sched_table, join_list, killed,
  77     // already_exiting
  78     lock_and_signal sched_lock;
  79     // The next scheduler id
  80     rust_sched_id max_sched_id;
  81     // A map from scheduler ids to schedulers. When this is empty
  82     // the kernel terminates
  83     sched_map sched_table;
  84     // A list of scheduler ids that are ready to exit
  85     std::vector<rust_sched_id> join_list;
  86     // Whether or not the runtime has to die (triggered when the root/main
  87     // task group fails). This propagates to all new schedulers and tasks
  88     // created after it is set.
  89     bool killed;
  90     bool already_exiting;
  91
  92
  93     rust_sched_reaper sched_reaper;
  94
  95     // The primary scheduler
  96     rust_sched_id main_scheduler;
  97     // The single-threaded scheduler that uses the main thread
  98     rust_sched_id osmain_scheduler;
  99     // Runs the single-threaded scheduler that executes tasks
 100     // on the main thread
 101     rust_sched_driver *osmain_driver;
 102
 103     // An atomically updated count of the live, 'non-weak' tasks
 104     uintptr_t non_weak_tasks;
 105
 106     rust_scheduler* get_scheduler_by_id_nolock(rust_sched_id id);
 107     void allow_scheduler_exit();
 108     void begin_shutdown();
 109
 110 public:
 111     struct rust_env *env;
 112
 113     rust_kernel(rust_env *env);
 114
 115     void log(uint32_t level, char const *fmt, ...);
 116     void fatal(char const *fmt, ...);
 117
 118     void *malloc(size_t size, const char *tag);
 119     void *realloc(void *mem, size_t size);
 120     void free(void *mem);
 121     rust_exchange_alloc *region() { return &exchange_alloc; }
 122
 123     void fail();
 124
 125     rust_sched_id create_scheduler(size_t num_threads);
 126     rust_sched_id create_scheduler(rust_sched_launcher_factory *launchfac,
 127                                    size_t num_threads, bool allow_exit);
 128     rust_scheduler* get_scheduler_by_id(rust_sched_id id);
 129     // Called by a scheduler to indicate that it is terminating
 130     void release_scheduler_id(rust_sched_id id);
 131     void wait_for_schedulers();
 132     int run();
 133
 134     rust_task_id generate_task_id();
 135
 136     void set_exit_status(int code);
 137
 138     rust_sched_id main_sched_id() { return main_scheduler; }
 139     rust_sched_id osmain_sched_id() { return osmain_scheduler; }
 140
 141     void inc_live_count();
 142     void dec_live_count();
 143
 144 };
 145
 146 template <typename T> struct kernel_owned {
 147     inline void *operator new(size_t size, rust_kernel *kernel,
 148                               const char *tag) {
 149         return kernel->malloc(size, tag);
 150     }
 151
 152     void operator delete(void *ptr) {
 153         ((T *)ptr)->kernel->free(ptr);
 154     }
 155 };
 156
 157 #endif /* RUST_KERNEL_H */
 158
 159 //
 160 // Local Variables:
 161 // mode: C++
 162 // fill-column: 78;
 163 // indent-tabs-mode: nil
 164 // c-basic-offset: 4
 165 // buffer-file-coding-system: utf-8-unix
 166 // End:
 167 //