1 /*! @page uhood Under the Hood
7 - Simulation Loop, LMM, sharing -> papers
8 - Context Switching, privatization -> papers
10 @section simgrid_uhood_s4u S4U
12 S4U classes are designed to be user process interfaces to Maestro resources.
13 We provide an uniform interface to them:
15 - automatic reference count with intrusive smart pointers `simgrid::s4u::FooPtr`
16 (also called `simgrid::s4u::Foo::Ptr`);
18 - manual reference count with `intrusive_ptr_add_ref(p)`,
19 `intrusive_ptr_release(p)` (which is the interface used by
20 [`boost::intrusive_ptr`](http://www.boost.org/doc/libs/1_61_0/libs/smart_ptr/intrusive_ptr.html));
22 - delegation of the operations to an opaque `pimpl` (which is the Maestro object);
24 - the Maestro object and the corresponding S4U object have the same lifetime
25 (and share the same reference count).
27 The ability to manipulate the objects through pointers and have the ability
28 to use explicit reference count management is useful for creating C wrappers
29 to the S4U and should play nicely with other language bindings (such as
32 Some objects currently live for the whole duration of the simulation and do
33 not have reference counts. We still provide dummy `intrusive_ptr_add_ref(p)`,
34 `intrusive_ptr_release(p)` and `FooPtr` for consistency.
36 In many cases, we try to have an API which is consistent with the API or
37 corresponding C++ standard classes. For example, the methods of
38 `simgrid::s4u::Mutex` are based on [`std::mutex`](http://en.cppreference.com/w/cpp/thread/mutex).
39 This has several benefits:
41 - we use a proven interface with a well defined and documented semantic;
43 - the interface is easy to understand and remember for people used to the C++
46 - we can use some standard C++ algorithms and helper classes with our types
47 (`simgrid::s4u::Mutex` can be used with
48 [`std::lock`](http://en.cppreference.com/w/cpp/thread/lock),
49 [`std::unique_lock`](http://en.cppreference.com/w/cpp/thread/unique_lock),
52 Example of `simgrid::s4u::Actor`:
56 // This is the corresponding maestro object:
57 friend simgrid::simix::Process;
58 simgrid::simix::Process* pimpl_ = nullptr;
61 Actor(simgrid::simix::Process* pimpl) : pimpl_(pimpl) {}
62 Actor(Actor const&) = delete;
63 Actor& operator=(Actor const&) = delete;
65 // Reference count is delegated to the S4u object:
66 friend void intrusive_ptr_add_ref(Actor* actor)
68 xbt_assert(actor != nullptr);
69 SIMIX_process_ref(actor->pimpl_);
71 friend void intrusive_ptr_release(Actor* actor)
73 xbt_assert(actor != nullptr);
74 SIMIX_process_unref(actor->pimpl_);
76 using Ptr = boost::intrusive_ptr<Actor>;
79 static Ptr createActor(const char* name, s4u::Host *host, double killTime, std::function<void()> code);
84 using ActorPtr = Actor::Ptr;
87 It uses the `simgrid::simix::Process` as an opaque pimple:
92 std::atomic_int_fast32_t refcount_ { 1 };
93 // The lifetime of the s4u::Actor is bound to the lifetime of the Process:
94 simgrid::s4u::Actor actor_;
96 Process() : actor_(this) {}
99 friend void intrusive_ptr_add_ref(Process* process)
101 // Atomic operation! Do not split in two instructions!
102 auto previous = (process->refcount_)++;
103 xbt_assert(previous != 0);
106 friend void intrusive_ptr_release(Process* process)
108 // Atomic operation! Do not split in two instructions!
109 auto count = --(process->refcount_);
117 smx_process_t SIMIX_process_ref(smx_process_t process)
119 if (process != nullptr)
120 intrusive_ptr_add_ref(process);
124 /** Decrease the refcount for this process */
125 void SIMIX_process_unref(smx_process_t process)
127 if (process != nullptr)
128 intrusive_ptr_release(process);
132 @section simgrid_uhood_mc Model Checker
134 The current implementation of the model-checker uses two distinct processes:
136 - the SimGrid model-checker (`simgrid-mc`) itself lives in the parent process;
138 - it spawns a child process for the SimGrid simulator/maestro and the simulated
141 They communicate using a `AF_UNIX` `SOCK_SEQPACKET` socket and exchange messages
142 defined in `mc_protocol.h`. The `SIMGRID_MC_SOCKET_FD` environment variable it
143 set to the file descriptor of this socket in the child process.
145 The model-checker analyzes, saves and restores the state of the model-checked
146 process using the following techniques:
148 - the model-checker reads and writes in the model-checked address space;
150 - the model-cheker `ptrace()`s the model-checked process and is thus able to
151 know the state of the model-checked process if it crashes;
153 - DWARF debug information are used to unwind the stack and identify local
156 - a custom heap is enabled in the model-checked process which allows the model
157 checker to know which chunks are allocated and which are freed.
159 @subsection simgrid_uhood_mc_address_space Address space
161 The `AddressSpace` is a base class used for both the model-checked process
162 and its snapshots and has methods to read in the corresponding address space:
164 - the `Process` class is a subclass representing the model-checked process;
166 - the `Snapshot` class is a subclass representing a snapshot of the process.
168 Additional helper class include:
170 - `Remote<T>` is the result of reading a `T` in a remote AddressSpace. For
171 trivial types (int, etc.), it is convertible t o `T`;
173 - `RemotePtr<T>` represents the address of an object of type `T` in some
174 remote `AddressSpace` (it could be an alias to `Remote<T*>`).
176 @subsection simgrid_uhood_mc_address_elf_dwarf ELF and DWARF
178 [ELF](http://refspecs.linuxbase.org/elf/elf.pdf) is a standard executable file
179 and dynamic libraries file format.
180 [DWARF](http://dwarfstd.org/) is a standard for debug information.
181 Both are used on GNU/Linux systems and exploited by the model-checker to
182 understand the model-checked process:
184 - `ObjectInformation` represents the information about a given ELF module
185 (executable or shared-object);
187 - `Frame` represents a subprogram scope (either a subprogram or a scope within
190 - `Type` represents a type (eg. `char*`, `int`, `std::string`) and is referenced
191 by variables (global, variables, parameters), functions (return type),
192 and other types (type of a `struct` field, etc.);
194 - `LocationList` and `DwarfExpression` are used to describe the location of