X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/4ff2e8482d23aa1d777df38e83ba988f6f18d1c4..1d8c6760b0e7ea8c87d9eb8cd0275f32eac3e6d4:/doc/doxygen/uhood.doc diff --git a/doc/doxygen/uhood.doc b/doc/doxygen/uhood.doc index b3f00f318a..67632a5d26 100644 --- a/doc/doxygen/uhood.doc +++ b/doc/doxygen/uhood.doc @@ -6,7 +6,128 @@ TBD - Simulation Loop, LMM, sharing -> papers - 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)` (which is the interface used by + [`boost::intrusive_ptr`](http://www.boost.org/doc/libs/1_61_0/libs/smart_ptr/intrusive_ptr.html)); + +- 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 explicit 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` are based on [`std::mutex`](http://en.cppreference.com/w/cpp/thread/mutex). +This has several 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`](http://en.cppreference.com/w/cpp/thread/lock), + [`std::unique_lock`](http://en.cppreference.com/w/cpp/thread/unique_lock), + etc.). + +Example of `simgrid::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; + + // Create processes: + static Ptr createActor(const char* name, s4u::Host *host, double killTime, std::function 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 @@ -69,10 +190,12 @@ simgrid::kernel::Future kernel_wait_until(double date) Like the experimental futures, we support chaining `.then()` methods with automatic future unwrapping. -You might want to look at some [C++ tutorial on futures](https://www.youtube.com/watch?v=mPxIegd9J3w&list=PLHTh1InhhwT75gykhs7pqcR_uSiG601oh&index=43) +You might want to look at some [tutorial on C++ futures](https://www.youtube.com/watch?v=mPxIegd9J3w&list=PLHTh1InhhwT75gykhs7pqcR_uSiG601oh&index=43) for more details and examples. Some operations of the proposed experimental futures are currently not implemented in our futures however such as -`.wait_for()`, `.wait_until()`, `shared_future`, `when_any()`. +`.wait_for()`, `.wait_until()`, +[`shared_future`](http://en.cppreference.com/w/cpp/thread/shared_future), +[`when_any()`](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0159r0.html#futures.when_any). \subsection simgrid_uhood_timer Timers @@ -82,25 +205,25 @@ 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 + - it spaws a child process for the SimGrid simulator/maestro and the simulated processes. -They communicate using a `AF_UNIX` `SOCK_DGRAM` socket and exchange messages +They communicate using a `AF_UNIX` `SOCK_SEQPACKET` 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-checker reads and writes in the model-checked address space; -* the model-cheker `ptrace()`s the model-checked process and is thus able to +- 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 +- 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 +- 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 @@ -115,16 +238,18 @@ and its snapshots and has methods to read in the corresponding address space: Additional helper class include: - `Remote` is the result of reading a `T` in a remote AddressSpace. For - trivial types (int, etc.), it is convertible t o `T`. + trivial types (int, etc.), it is convertible t o `T`; - `RemotePtr` represents the address of an object of type `T` in some remote `AddressSpace` (it could be an alias to `Remote`). \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: +[ELF](http://refspecs.linuxbase.org/elf/elf.pdf) is a standard executable file +and dynamic libraries file format. +[DWARF](http://dwarfstd.org/) 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); @@ -132,7 +257,7 @@ and exploited by the model-checker to understand the model-checked process: - `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 + - `Type` represents a type (eg. `char*`, `int`, `std::string`) and is referenced by variables (global, variables, parameters), functions (return type), and other types (type of a `struct` field, etc.);