Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
213049a25742b97f7b0f52d31de1d36360e56d4f
[simgrid.git] / 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 ready for public use yet</b>. You should not go
10          that path unless you know what you are doing.  If unsure,
11          proceed to @ref MSG_API instead.
12
13 Unsurprisingly, the S4U interface matches the concepts presented in 
14 @ref starting_components "the introduction". You should read this page
15 first, to not get lost in the amount of classes provided here.
16
17 @section s4u_raii Memory Management of S4U objects
18
19 For sake of simplicity, we use
20 [RAII](https://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization)
21 everywhere in S4U. This is an idiom where resources are automatically
22 managed through the context. Provided that you never manipulate
23 objects of type Foo directly but always FooPtr references, you will
24 never have to explicitely release the resource that you use nor to
25 free the memory of unused objects.
26
27 Here is a little example:
28
29 @code{cpp}
30 void myFunc() 
31 {
32   simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::createMutex(); // Too bad we cannot use `new` here
33
34   mutex->lock();   // use the mutex as a simple reference
35   //  bla bla
36   mutex->unlock(); 
37   
38 } // The mutex will get automatically freed because the only existing reference gets out of scope
39 @endcode
40 */