doc/doxygen/module-s4u.doc

   1 /**
   2 @defgroup s4u_api  S4U: Next Generation SimGrid API
   3 @brief Future core API, mixing the full power of SimGrid to the power of C++.
   4
   5 The S4U API is currently under heavy work, but will eventually
   6 deprecate the MSG and SimDag APIs. Everything that you can do in
   7 SimGrid will be possible in S4U.
   8
   9 @warning <b>S4U is not as rock stable as the rest of SimGrid yet</b>.
  10          You are really welcome to test it, but be warned that the API
  11          may change without notice between releases. This is however
  12          the way to go if you want to create a new long-term project.
  13          If you want to play safe, proceed to @ref MSG_API instead.
  14
  15 Unsurprisingly, the S4U interface matches the concepts presented in
  16 @ref starting_components "the introduction". You should read this page
  17 first, to not get lost in the amount of classes provided here. Or you
  18 could jump to the \ref s4u_examples directly if you prefer.
  19
  20 @section s4u_raii Memory Management of S4U objects
  21
  22 For sake of simplicity, we use
  23 [RAII](https://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization)
  24 everywhere in S4U. This is an idiom where resources are automatically
  25 managed through the context. Provided that you never manipulate
  26 objects of type Foo directly but always FooPtr references (which are
  27 [boost::intrusive_ptr](http://www.boost.org/doc/libs/1_61_0/libs/smart_ptr/intrusive_ptr.html)&lt;Foo&gt;),
  28 you will never have to explicitely release the resource that you use
  29 nor to free the memory of unused objects.
  30
  31 Here is a little example:
  32
  33 @code{cpp}
  34 void myFunc()
  35 {
  36   simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::createMutex(); // Too bad we cannot use `new` here
  37
  38   mutex->lock();   // use the mutex as a simple reference
  39   //  bla bla
  40   mutex->unlock();
  41
  42 } // The mutex will get automatically freed because the only existing reference gets out of scope
  43 @endcode
  44 */