From 34de77922896f906099c696228ce2a55d9501ff9 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sat, 23 Dec 2017 09:02:51 +0100 Subject: [PATCH] deprecate MSG in the documentation --- ChangeLog | 9 +++++++++ NEWS | 3 ++- doc/doxygen/index.doc | 2 +- doc/doxygen/module-msg.doc | 16 +++++++++------- doc/doxygen/module-s4u.doc | 18 +++++++++--------- doc/doxygen/module-sd.doc | 6 ++++-- examples/msg/README.doc | 4 ++++ 7 files changed, 38 insertions(+), 20 deletions(-) diff --git a/ChangeLog b/ChangeLog index a0ccaca26d..5ef7aa1bd6 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,12 @@ SimGrid (3.18) NOT RELEASED YET (target: December 24 2017) + The "Ho Ho Ho! SimGrid 4 beta is coming to town" release. + + MSG IS NOW DEPRECATED. Please use S4U for new projects. + - Support for MSG should not be removed from SimGrid before 2020, + but future evolutions will be limited to the integration of + user-provided patches. + S4U New features - s4u::onDeadlock() signal, run before stopping the simulation. - s4u::Exec: asynchronous executions (abstraction of background @@ -23,6 +30,8 @@ SimGrid (3.18) NOT RELEASED YET (target: December 24 2017) name implies on both sequential and parallel tasks. - Both changes fix GitHub's #223 using PR #237 as a basis. Thanks Michael Mercier. + - Most examples were converted to S4U and hidden elsewhere at tests. + Rational: we still want MSG to work; we want newcomers to use S4U. SURF - LMM stuff moved to its own namespace: simgrid::kernel::lmm. diff --git a/NEWS b/NEWS index decbae7c1a..ec8a93a59a 100644 --- a/NEWS +++ b/NEWS @@ -5,9 +5,10 @@ __ _____ _ __ ___(_) ___ _ __ |___ / / |( _ ) \_/ \___|_| |___/_|\___/|_| |_| |____(_)_|\___/ (not released yet) -The "Ho Ho Ho! SimGrid 4 is coming to town" release. +The "Ho Ho Ho! SimGrid 4 beta is coming to town" release. * Convert most of (but not all) MSG examples to S4U. + SimGrid 4 *may* be there by the next solstice. * New model: energy consumption due to the network. * Major cleanups in the disk and storage subsystems. * (+ further deprecate XBT, bug fixes and doc improvement) diff --git a/doc/doxygen/index.doc b/doc/doxygen/index.doc index b12ea4fea0..fcee10d514 100644 --- a/doc/doxygen/index.doc +++ b/doc/doxygen/index.doc @@ -17,9 +17,9 @@ - @subpage tutorial_smpi "Tutorials with SMPI" - @subpage application - @subpage s4u_api + - @subpage SMPI_API - @subpage MSG_API - @subpage SD_API - - @subpage SMPI_API - @subpage MSG_Java - @subpage platform - @subpage models diff --git a/doc/doxygen/module-msg.doc b/doc/doxygen/module-msg.doc index a106c5677f..3ef2a6c069 100644 --- a/doc/doxygen/module-msg.doc +++ b/doc/doxygen/module-msg.doc @@ -1,7 +1,8 @@ /** -@defgroup MSG_API MSG: Simulate CSP Algorithms +@defgroup MSG_API MSG: Legacy handling of CSP algorithms @brief Simple programming environment + MSG is a simple API to write algorithms organized with Concurrent Sequential Processes (CSP) that interact by exchanging messages. It constitutes a convenient simplification of the reality of distributed @@ -9,12 +10,13 @@ systems. It can be used to build rather realistic simulations, but remains simple to use: most unpleasant technical elements can be abstracted away rather easily. -If you are unsure, then you probably want to use MSG. Otherwise, you -may want to use one of the following: - - - MSG in Java instead of C: @ref MSG_Java. - - If you want to use DAGs: @ref SD_API. - - If you want to study a MPI application: @ref SMPI_API. +\warning MSG used to be the main API of SimGrid 3, but we are + currently in the process of releasing SimGrid 4. The + tentative release date is Summer 2018. So MSG is frozen and + will probably never evolve. If you are starting a new + project, you should consider S4U instead. Note that the + support for MSG will not be removed from SimGrid before 2020 + at least. \section MSG_funct Offered functionalities - \ref msg_simulation diff --git a/doc/doxygen/module-s4u.doc b/doc/doxygen/module-s4u.doc index abd1c3c833..fe5d8bf9ef 100644 --- a/doc/doxygen/module-s4u.doc +++ b/doc/doxygen/module-s4u.doc @@ -1,16 +1,16 @@ /** -@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. +The S4U API is near from its final state. Everything that you can do in +SimGrid should be possible in S4U and the missing pieces are seen as +bugs. -@warning S4U is not as rock stable as the rest of SimGrid yet. - 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. +@warning S4U is still evolving: v3.18 is a beta release. You + are really welcome to test it, but this API may change + 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 deprecated @ref MSG_API instead. Unsurprisingly, the S4U interface matches the concepts presented in @ref starting_components "the introduction". You should read this page diff --git a/doc/doxygen/module-sd.doc b/doc/doxygen/module-sd.doc index 25c855fc52..e739dca3d1 100644 --- a/doc/doxygen/module-sd.doc +++ b/doc/doxygen/module-sd.doc @@ -1,5 +1,5 @@ /** -@defgroup SD_API SimDag: Simulate DAG algorithms +@defgroup SD_API SimDag: Legacy handling of DAG algorithms @brief Programming environment for DAG applications SimDag provides functionnalities to simulate parallel task scheduling @@ -8,7 +8,9 @@ can be expressed with SimDag; consider using @ref MSG_API "MSG" for distributed algorithms). SimDag is the oldest interface in SimGrid, even if it was temporarly -removed when the new superfast kernel was added in SimGrid v3.0. +removed when the new superfast kernel was added in SimGrid v3.0. It +will certainly be deprecated by future releases of the S4U API, when +inter-activity dependencies are added. @{ diff --git a/examples/msg/README.doc b/examples/msg/README.doc index c738a68ae9..203c2495d2 100644 --- a/examples/msg/README.doc +++ b/examples/msg/README.doc @@ -13,6 +13,10 @@ documentation, but it should remain readable directly. - @ref msg_ex_models - @ref msg_ex_ns3 +@warning MSG was deprecated in SimGrid v3.18. These examples should be + converted to S4U in the next releases. You really should + consider using S4U in your next project. + @section msg_ex_basics Basic examples and features - Master Workers. -- 2.20.1