/**
-@defgroup s4u_api S4U: Next Generation SimGrid API
+@defgroup s4u_api S4U: Next generation SimGrid API
@brief Future core API, mixing the full power of SimGrid to the power of C++.
-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.
+@b TLDR: The best documentation is the @ref s4u_examples
-@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.
+Currently (v3.21), S4U is definitely the way to go for long-term
+projects. It is feature complete, but may still evolve slightly in the
+future releases. It can already be used to do everything that can be
+done in SimGrid, but you may have to adapt your code in future
+releases. When this happens, compiling your code will produce
+deprecation warnings for 4 releases (one year) before the removal of
+the old symbols.
+If you want an API that will never ever evolve in the future, proceed
+to the deprecated @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. Or you
-could jump to the \ref s4u_examples directly if you prefer.
+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.
@section s4u_raii Memory Management of S4U objects
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)<Foo>),
+[boost::intrusive_ptr](http://www.boost.org/doc/libs/1_61_0/libs/smart_ptr/intrusive_ptr.html)<Foo>),
you will never have to explicitely release the resource that you use
nor to free the memory of unused objects.
@code{cpp}
void myFunc()
{
- simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::createMutex(); // Too bad we cannot use `new` here
+ simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::create(); // Too bad we cannot use `new` here
mutex->lock(); // use the mutex as a simple reference
// bla bla
