- Context Switching, privatization -> papers
- @subpage inside
+\section simgrid_uhood_s4u S4U
+
+S4U classes are designed to be user process interfaces to Maestro resources.
+We provide an uniform interface to them:
+
+* automatic reference count with intrusive smart pointers `simgrid::s4u::FooPtr`
+ (also called `simgrid::s4u::Foo::Ptr`);
+
+* manual reference count with `intrusive_ptr_add_ref(p)`,
+ `intrusive_ptr_release(p)`;
+
+* delegation of the operations to a opaque `pimpl` (which is the Maestro object);
+
+* the Maestro object and the corresponding S4U object have the same lifetime
+ (and share the same reference count).
+
+The ability to manipulate thge objects thought pointers and have the ability
+to use explicite reference count management is useful for creating C wrappers
+to the S4U and should play nicely with other language bindings (such as
+SWIG-based ones).
+
+Some objects currently live for the whole duration of the simulation and do
+not have refertence counts. We still provide dummy `intrusive_ptr_add_ref(p)`,
+`intrusive_ptr_release(p)` and `FooPtr` for consistency.
+
+In many cases, we try to have a API which is consistent with the API or
+corresponding C++ standard classes. For example, the methods of
+`simgrid::s4u::Mutex`. This has different benefits:
+
+ * we use a proven interface with a well defined and documented semantic;
+
+ * the interface is easy to understand and remember for people used to the C++
+ standard interface;
+
+ * we can use some standard C++ algorithms and helper classes with our types
+ (`simgrid::s4u::Mutex` can be used with `std::lock`, `std::unique_lock`,
+ etc.).
+
+Example of `simgris::s4u::Actor`:
+
+~~~
+class Actor {
+ // This is the corresponding maestro object:
+ friend simgrid::simix::Process;
+ simgrid::simix::Process* pimpl_ = nullptr;
+public:
+
+ Actor(simgrid::simix::Process* pimpl) : pimpl_(pimpl) {}
+ Actor(Actor const&) = delete;
+ Actor& operator=(Actor const&) = delete;
+
+ // Reference count is delegated to the S4u object:
+ friend void intrusive_ptr_add_ref(Actor* actor)
+ {
+ xbt_assert(actor != nullptr);
+ SIMIX_process_ref(actor->pimpl_);
+ }
+ friend void intrusive_ptr_release(Actor* actor)
+ {
+ xbt_assert(actor != nullptr);
+ SIMIX_process_unref(actor->pimpl_);
+ }
+ using Ptr = boost::intrusive_ptr<Actor>;
+
+ // Create processes:
+ static Ptr createActor(const char* name, s4u::Host *host, double killTime, std::function<void()> code);
+
+ // [...]
+};
+
+using ActorPtr = Actor::Ptr;
+~~~
+
+It uses the `simgrid::simix::Process` as a opaque pimple:
+
+~~~
+class Process {
+private:
+ std::atomic_int_fast32_t refcount_ { 1 };
+ // The lifetime of the s4u::Actor is bound to the lifetime of the Process:
+ simgrid::s4u::Actor actor_;
+public:
+ Process() : actor_(this) {}
+
+ // Reference count:
+ friend void intrusive_ptr_add_ref(Process* process)
+ {
+ // Atomic operation! Do not split in two instructions!
+ auto previous = (process->refcount_)++;
+ xbt_assert(previous != 0);
+ (void) previous;
+ }
+ friend void intrusive_ptr_release(Process* process)
+ {
+ // Atomic operation! Do not split in two instructions!
+ auto count = --(process->refcount_);
+ if (count == 0)
+ delete process;
+ }
+
+ // [...]
+};
+
+smx_process_t SIMIX_process_ref(smx_process_t process)
+{
+ if (process != nullptr)
+ intrusive_ptr_add_ref(process);
+ return process;
+}
+
+/** Decrease the refcount for this process */
+void SIMIX_process_unref(smx_process_t process)
+{
+ if (process != nullptr)
+ intrusive_ptr_release(process);
+}
+~~~
+
\section simgrid_uhood_async Asynchronous operations
\subsection simgrid_uhood_futures Futures
\subsection simgrid_uhood_timer Timers
+\section simgrid_uhood_mc Model Checker
+
+The current implementation of the model-checker uses two distinct processes:
+
+ - the SimGrid model-checker (`simgrid-mc`) itself lives in the parent process;
+
+ - it spaws a child process for the SimGrid simulator/mastro and the simulated
+ processes.
+
+They communicate using a `AF_UNIX` `SOCK_DGRAM` socket and exchange messages
+defined in `mc_protocol.h`. The `SIMGRID_MC_SOCKET_FD` environment variable it
+set to the file descriptor of this socket in the child process.
+
+The model-checker analyzes, saves and restores the state of the model-checked
+process using the following techniques:
+
+* the model-checker reads and writes in the model-checked address space;
+
+* the model-cheker `ptrace()`s the model-checked process and is thus able to
+ know the state of the model-checked process if it crashes;
+
+* DWARF debug informations are used to unwind the stack and identify local
+ variables;
+
+* a custom heap is enabled in the model-checked process which allows the model
+ checker to know which chunks are allocated and which are freed.
+
+\subsection simgrid_uhood_mc_address_space Address space
+
+The `AddressSpace` is a base class used for both the model-checked process
+and its snapshots and has methods to read in the corresponding address space:
+
+ - the `Process` class is a subclass representing the model-checked process;
+
+ - the `Snapshot` class is a subclass representing a snapshot of the process.
+
+Additional helper class include:
+
+ - `Remote<T>` is the result of reading a `T` in a remote AddressSpace. For
+ trivial types (int, etc.), it is convertible t o `T`.
+
+ - `RemotePtr<T>` represents the address of an object of type `T` in some
+ remote `AddressSpace` (it could be an alias to `Remote<T*>`).
+
+\subsection simgrid_uhood_mc_address_elf_dwarf ELF and DWARF
+
+ELF is a standard executable file and dynamic libraries file format.
+DWARF is a standard for debug informations. Both are used on GNU/Linux systems
+and exploited by the model-checker to understand the model-checked process:
+
+ - `ObjectInformation` represents the informations about a given ELF module
+ (executable or shared-object);
+
+ - `Frame` represents a subprogram scope (either a subprogram or a scope within
+ the subprogram);
+
+ - `Type` represents a type (`char*`, `int`, `std::string`) and is referenced
+ by variables (global, variables, parameters), functions (return type),
+ and other types (type of a `struct` field, etc.);
+
+ - `LocationList` and `DwarfExpression` are used to describe the location of
+ variables.
+
*/
