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++.
5 @b TLDR: The best documentation is the @ref s4u_examples
7 Currently (v3.21), S4U is definitely the way to go for long-term
8 projects. It is feature complete, but may still evolve slightly in the
9 future releases. It can already be used to do everything that can be
10 done in SimGrid, but you may have to adapt your code in future
11 releases. When this happens, compiling your code will produce
12 deprecation warnings for 4 releases (one year) before the removal of
14 If you want an API that will never ever evolve in the future, proceed
15 to the deprecated @ref MSG_API instead.
17 The S4U interface matches the concepts presented in @ref
18 starting_components "the introduction". You should read this page
19 first, to not get lost in the amount of classes provided here.
21 @section s4u_raii Memory Management of S4U objects
23 For sake of simplicity, we use
24 [RAII](https://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization)
25 everywhere in S4U. This is an idiom where resources are automatically
26 managed through the context. Provided that you never manipulate
27 objects of type Foo directly but always FooPtr references (which are
28 [boost::intrusive_ptr](http://www.boost.org/doc/libs/1_61_0/libs/smart_ptr/intrusive_ptr.html)<Foo>),
29 you will never have to explicitely release the resource that you use
30 nor to free the memory of unused objects.
32 Here is a little example:
37 simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::create(); // Too bad we cannot use `new` here
39 mutex->lock(); // use the mutex as a simple reference
43 } // The mutex will get automatically freed because the only existing reference gets out of scope
