From d4729dbbb22bd34542046d553605a57f356d94fe Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Thu, 20 Sep 2018 21:35:26 +0200 Subject: [PATCH] convert the remain bits of S4U doc into sphinx --- doc/doxygen/module-s4u.doc | 45 -------------------------------------- docs/source/app_s4u.rst | 38 +++++++++++++++++++++++++++++++- 2 files changed, 37 insertions(+), 46 deletions(-) delete mode 100644 doc/doxygen/module-s4u.doc diff --git a/doc/doxygen/module-s4u.doc b/doc/doxygen/module-s4u.doc deleted file mode 100644 index ac2d360367..0000000000 --- a/doc/doxygen/module-s4u.doc +++ /dev/null @@ -1,45 +0,0 @@ -/** -@defgroup s4u_api S4U: Next generation SimGrid API -@brief Future core API, mixing the full power of SimGrid to the power of C++. - -@b TLDR: The best documentation is the @ref s4u_examples - -Currently (v3.21), S4U is definitely the way to go for long-term -projects. It is feature complete, but may still evolve slightly in the -future releases. It can already be used to do everything that can be -done in SimGrid, but you may have to adapt your code in future -releases. When this happens, compiling your code will produce -deprecation warnings for 4 releases (one year) before the removal of -the old symbols. -If you want an API that will never ever evolve in the future, proceed -to the deprecated @ref MSG_API instead. - -The S4U interface matches the concepts presented in @ref -starting_components "the introduction". You should read this page -first, to not get lost in the amount of classes provided here. - -@section s4u_raii Memory Management of S4U objects - -For sake of simplicity, we use -[RAII](https://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) -everywhere in S4U. This is an idiom where resources are automatically -managed through the context. Provided that you never manipulate -objects of type Foo directly but always FooPtr references (which are -[boost::intrusive_ptr](http://www.boost.org/doc/libs/1_61_0/libs/smart_ptr/intrusive_ptr.html)<Foo>), -you will never have to explicitely release the resource that you use -nor to free the memory of unused objects. - -Here is a little example: - -@code{cpp} -void myFunc() -{ - simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::create(); // Too bad we cannot use `new` here - - mutex->lock(); // use the mutex as a simple reference - // bla bla - mutex->unlock(); - -} // The mutex will get automatically freed because the only existing reference gets out of scope -@endcode -*/ diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index f9f93bb96b..8d4ec2be63 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -21,6 +21,16 @@ with the full power of C++. This is the preferred interface to describe abstract algorithms in the domains of Cloud, P2P, HPC, IoT, and similar settings. +Currently (v3.21), S4U is definitely the way to go for long-term +projects. It is feature complete, but may still evolve slightly in the +future releases. It can already be used to do everything that can be +done in SimGrid, but you may have to adapt your code in future +releases. When this happens, compiling your code will produce +deprecation warnings for 4 releases (one year) before the removal of +the old symbols. +If you want an API that will never ever evolve in the future, you +should use the deprecated MSG API instead. + ------------- Main Concepts ------------- @@ -212,6 +222,32 @@ Activities Life cycle Sometimes, you want to change the setting of an activity before it even starts. -.. todo:: fill this section +.. todo:: write this section + +----------------- +Memory Management +----------------- + +For sake of simplicity, we use `RAII +`_ +everywhere in S4U. This is an idiom where resources are automatically +managed through the context. Provided that you never manipulate +objects of type Foo directly but always FooPtr references (which are +defined as `boost::intrusive_ptr +`_ +), you will never have to explicitely release the resource that +you use nor to free the memory of unused objects. + +Here is a little example: + +.. code-block:: cpp + void myFunc() + { + simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::create(); // Too bad we cannot use `new` + mutex->lock(); // use the mutex as a simple reference + // bla bla + mutex->unlock(); + + } // The mutex gets automatically freed because the only existing reference gets out of scope -- 2.20.1