s4u is not that bad anymore

[simgrid.git] / doc / doxygen / module-s4u.doc

diff --git a/doc/doxygen/module-s4u.doc b/doc/doxygen/module-s4u.doc
index 9e629e1..abd1c3c 100644 (file)
--- a/doc/doxygen/module-s4u.doc
+++ b/doc/doxygen/module-s4u.doc
@@ -6,132 +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. 
 
 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.
-
-@section s4u_funct Offered functionalities
+@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 
 
 Unsurprisingly, the S4U interface matches the concepts presented in 

-@ref starting_components "the introduction":
-
-  - @ref s4u_actor
-
-  @{
+@ref starting_components "the introduction". You should read this page
+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

 */
 */

-
-/** @defgroup  s4u_actor Actors: simulation agents */
-
-/** @} */
-
-   - \ref msg_simulation
-   - \ref m_process_management
-   - \ref m_host_management
-   - \ref m_task_management
-   - \ref msg_mailbox_management
-   - @ref msg_file
-   - \ref msg_task_usage
-   - \ref msg_VMs
-   - \ref msg_synchro
-   - \ref msg_trace_driven
-   - \ref MSG_examples
-
-@defgroup msg_simulation   Main MSG simulation Functions
-@ingroup MSG_API
-@brief How to setup and control your simulation.
-
-The basic workflow is the following (check the \ref MSG_examples for
-details).
-
- -# Initialize the library with #MSG_init
- -# Create a platform (usually by parsing a file with
-    #MSG_create_environment)
- -# Register the functions that your processes are supposed to run with
-    #MSG_function_register (and maybe #MSG_function_register_default)
- -# Launch your processes from a deployment file with #MSG_launch_application
- -# Run the simulation with #MSG_main
-*
-
-** @defgroup m_process_management Process Management Functions
- *  @ingroup MSG_API
- *  @brief This section describes the process structure of MSG
- *         (#msg_process_t) and the functions for managing it.
- */
-
-** @defgroup m_host_management Host Management Functions
- *  @ingroup MSG_API
- *  @brief Host structure of MSG
- *
-
-** @defgroup m_task_management Task Management Functions
- *  @ingroup MSG_API
- *  @brief Task structure of MSG (#msg_task_t) and associated functions. See
- *         \ref msg_task_usage to see how to put the tasks in action.
- *
-
-** @defgroup msg_mailbox_management Mailbox Management Functions
- *  @ingroup MSG_API
- *  @brief Mailbox structure of MSG (#msg_mailbox_t) and associated functions.
- *
-
-** @defgroup msg_task_usage Task Actions
- *  @ingroup MSG_API
- *  @brief This section describes the functions that can be used
- *         by a process to execute, communicate or otherwise handle some task.
- *
-
-** @defgroup msg_synchro Explicit Synchronization Functions
- *  @ingroup MSG_API
- *  @brief Explicit synchronization mechanisms: semaphores (#msg_sem_t) and friends.
- *
- * In some situations, these things are very helpful to synchronize processes without message exchanges.
- *
-
-** @defgroup msg_VMs VMs
- *  @ingroup MSG_API
- *  @brief Interface created to mimic IaaS clouds.
- *
- *  With it, you can create virtual machines to put your processes
- *  into, and interact directly with the VMs to manage groups of
- *  processes.
- *
- *  This interface is highly experimental at this point. Testing is
- *  welcomed, but do not expect too much of it right now. Even the
- *  interfaces may be changed in future releases of SimGrid (although
- *  things are expected to stabilize nicely before SimGrid v3.8).
- *  There is no guaranty on the rest of SimGrid, and there is less
- *  than that on this part.
- *
- *
-
-** @defgroup msg_storage_management Storage Management Functions
- *  @ingroup MSG_API
- *  @brief Storage structure of MSG (#msg_storage_t) and associated functions, inspired from POSIX.
- *
-
-** @defgroup msg_file File Management Functions
-    @ingroup MSG_API
-    @brief MSG files (#msg_file_t) and associated functions, inspired from POSIX.
-*
-
-**
-@defgroup msg_trace_driven Trace-driven simulations
-@ingroup MSG_API
-@brief This section describes the functions allowing to build trace-driven simulations.
-
-This is very handy when you want to test an algorithm or protocol that
-does nothing unless it receives some events from outside. For example,
-a P2P protocol reacts to requests from the user, but does nothing if
-there is no such event.
-
-In such situations, SimGrid allows to write your protocol in your C
-file, and the events to react to in a separate text file. Declare a
-function handling each of the events that you want to accept in your
-trace files, register them using #xbt_replay_action_register in your main,
-and then use #MSG_action_trace_run to launch the simulation. You can
-either have one trace file containing all your events, or a file per
-simulated process.
-
-Check the examples in <b>examples/msg/actions/actions.c</b> for details.
-
- *