X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/0c3da2d0a2782eda66c3b6e191895c63f56dfeae..22e6546d2c6f14864cc93c4ed1470d8e8c1e2d95:/doc/doxygen/module-s4u.doc

diff --git a/doc/doxygen/module-s4u.doc b/doc/doxygen/module-s4u.doc
index 324edb0fcc..abd1c3c833 100644
--- a/doc/doxygen/module-s4u.doc
+++ b/doc/doxygen/module-s4u.doc
@@ -6,13 +6,39 @@ The S4U API is currently under heavy work, but will eventually
 deprecate the MSG and SimDag APIs. Everything that you can do in
 SimGrid will be possible in S4U. 
 
-@warning <b>S4U is not ready for public use yet</b>. You should not go
-	 that path unless you know what you are doing.  If unsure,
-	 proceed to @ref MSG_API instead.
-
+@warning <b>S4U is not as rock stable as the rest of SimGrid yet</b>. 
+	 You are really welcome to test it, but be warned that the API
+	 may change without notice between releases. This is however
+	 the way to go if you want to create a new long-term project.
+	 If you want to play safe, proceed to @ref MSG_API instead. 
 
 Unsurprisingly, 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.
+first, to not get lost in the amount of classes provided here. Or you
+could jump to the \ref s4u_examples directly if you prefer.
+
+@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)&lt;Foo&gt;),
+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::createMutex(); // 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
 */