elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
}
</script>
- <br />
- <br />
+ <br>
+ <br>
You can extend SimGrid without modifying it, thanks to our plugin
mechanism. This page describes how to write your own plugin, and
Host Energy
===========
-.. doxygengroup:: Plugin_host_energy
+.. doxygengroup:: plugin_host_energy
Link Energy
===========
-.. doxygengroup:: Plugin_link_energy
+.. doxygengroup:: plugin_link_energy
Host Load
=========
-.. doxygengroup:: Plugin_host_load
+.. doxygengroup:: plugin_host_load
File System
===========
-.. doxygengroup:: Plugin_filesystem
+.. doxygengroup:: plugin_filesystem
.. LocalWords: SimGrid
memory gets properly reclaimed. This call should be at the end of the
actor's function, not in a on_exit callback.
+.. _s4u_raii:
+
Memory Management
*****************
.. autodoxymethod:: sg_actor_attach(const char *name, void *data, sg_host_t host, xbt_dict_t properties)
.. autodoxymethod:: sg_actor_detach()
- .. autodoxymethod:: sg_actor_ref(sg_actor_t actor)
- .. autodoxymethod:: sg_actor_unref(sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_ref(const_sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_unref(const_sg_actor_t actor)
Searching specific actors
-------------------------
.. group-tab:: C
- .. autodoxymethod:: sg_actor_get_name(sg_actor_t actor)
- .. autodoxymethod:: sg_actor_get_PID(sg_actor_t actor)
- .. autodoxymethod:: sg_actor_get_PPID(sg_actor_t actor)
- .. autodoxymethod:: sg_actor_get_properties(sg_actor_t actor)
- .. autodoxymethod:: sg_actor_get_property_value(sg_actor_t actor, const char *name)
+ .. autodoxymethod:: sg_actor_get_name(const_sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_get_PID(const_sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_get_PPID(const_sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_get_properties(const_sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_get_property_value(const_sg_actor_t actor, const char *name)
- .. autodoxymethod:: sg_actor_get_host(sg_actor_t actor)
+ .. autodoxymethod:: sg_actor_get_host(const_sg_actor_t actor)
.. autodoxymethod:: sg_actor_set_host(sg_actor_t actor, sg_host_t host)
.. autodoxymethod:: sg_actor_data(const_sg_actor_t actor)
.. autodoxymethod:: simgrid::s4u::Engine::get_netzone_root()
.. autodoxymethod:: simgrid::s4u::Engine::netpoint_by_name_or_null(const std::string &name)
.. autodoxymethod:: simgrid::s4u::Engine::netzone_by_name_or_null(const std::string &name)
- .. autodoxymethod:: simgrid::s4u::Engine::set_netzone_root(NetZone *netzone)
+ .. autodoxymethod:: simgrid::s4u::Engine::set_netzone_root(const NetZone *netzone)
Signals
-------
class Mutex;
XBT_PUBLIC void intrusive_ptr_release(const Mutex* m);
XBT_PUBLIC void intrusive_ptr_add_ref(const Mutex* m);
-/** Smart pointer to a simgrid::s4u::Mutex */
+/**
+ * @beginrst
+ * Smart pointer to a :cpp:type:`simgrid::s4u::Mutex`
+ * @endrst
+ */
typedef boost::intrusive_ptr<Mutex> MutexPtr;
class NetZone;
XBT_PUBLIC const char* sg_host_self_get_name();
-/** @brief Return the total count of pstates defined for a host. See also @ref plugin_energy.
+/** @brief Return the total count of pstates defined for a host.
+ *
+ * @beginrst
+ * See also :ref:`plugin_host_energy`.
+ * @endrst
*
* @param host host to test
*/
XBT_PUBLIC void MSG_host_set_pstate(sg_host_t host, int pstate);
/** @brief Start the host if it is off
*
- * See also #MSG_host_is_on() to test the current state of the host and @ref SURF_plugin_energy
+ * @beginrst
+ * See also :cpp:func:`MSG_host_is_on()` to test the current state of the host, and :ref:`plugin_host_energy`
* for more info on DVFS.
+ * @endrst
*/
XBT_PUBLIC void MSG_host_on(sg_host_t h);
/** @brief Stop the host if it is on
*
- * See also MSG_host_is_on() to test the current state of the host and @ref SURF_plugin_energy
+ * @beginrst
+ * See also :cpp:func:`MSG_host_is_on()` to test the current state of the host, and :ref:`plugin_host_energy`
* for more info on DVFS.
+ * @endrst
*/
XBT_PUBLIC void MSG_host_off(sg_host_t h);
XBT_PUBLIC int MSG_host_is_on(const_sg_host_t h);
/************************** Global ******************************************/
/** @brief set a configuration variable
*
- * Do --help on any simgrid binary to see the list of currently existing configuration variables, and see Section @ref
- * options.
+ * @beginrst
+ * Do --help on any simgrid binary to see the list of currently existing configuration variables, and see Section
+ * :ref:`options`.
+ * @endrst
*
* Example:
* MSG_config("host/model","ptask_L07");
static bool is_initialized();
/** @brief set a configuration variable
*
- * Do --help on any simgrid binary to see the list of currently existing configuration variables (see also @ref
- * options).
+ * @beginrst
+ * Do --help on any simgrid binary to see the list of currently existing configuration variables
+ * (see also :ref:`options`).
+ * @endrst
*
* Example:
* e->set_config("host/model:ptask_L07");
*
* Some physical resource with computing and networking capabilities on which Actors execute.
*
+ * @beginrst
* All hosts are automatically created during the call of the method
- * @ref simgrid::s4u::Engine::load_platform().
+ * :cpp:func:`simgrid::s4u::Engine::load_platform()`.
* You cannot create a host yourself.
*
- * You can retrieve a particular host using @ref simgrid::s4u::Host::by_name()
- * and actors can retrieve the host on which they run using @ref simgrid::s4u::Host::current() or
- * @ref simgrid::s4u::this_actor::get_host().
+ * You can retrieve a particular host using :cpp:func:`simgrid::s4u::Host::by_name()`
+ * and actors can retrieve the host on which they run using :cpp:func:`simgrid::s4u::Host::current()` or
+ * :cpp:func:`simgrid::s4u::this_actor::get_host()`
+ * @endrst
*/
class XBT_PUBLIC Host : public xbt::Extendable<Host> {
friend vm::VMModel; // Use the pimpl_cpu to compute the VM sharing
* Instead, you should use the present class, that is a drop-in replacement of
* <a href="http://en.cppreference.com/w/cpp/thread/mutex">std::mutex</a>.
*
- * As for any S4U object, Mutexes are using the @ref s4u_raii "RAII idiom" for memory management.
- * Use create() to get a simgrid::s4u::MutexPtr to a newly created mutex and only manipulate simgrid::s4u::MutexPtr.
+ * @beginrst
+ * As for any S4U object, Mutexes are using the :ref:`RAII idiom <s4u_raii>` for memory management.
+ * Use :cpp:func:`create() <simgrid::s4u::Mutex::create()>` to get a :cpp:type:`simgrid::s4u::MutexPtr` to a newly
+ * created mutex, and only manipulate :cpp:type:`simgrid::s4u::MutexPtr`.
+ * @endrst
*
*/
class XBT_PUBLIC Mutex {
friend XBT_PUBLIC void intrusive_ptr_release(const Mutex* mutex);
public:
+#ifndef DOXYGEN
explicit Mutex(kernel::activity::MutexImpl* mutex) : pimpl_(mutex) {}
~Mutex();
- // No copy:
- /** You cannot create a new mutex by copying an existing one. Use MutexPtr instead */
- Mutex(Mutex const&) = delete;
- /** You cannot create a new mutex by value assignment either. Use MutexPtr instead */
- Mutex& operator=(Mutex const&) = delete;
+ Mutex(Mutex const&) = delete; // No copy constructor; Use MutexPtr instead
+ Mutex& operator=(Mutex const&) = delete; // No direct assignment either. Use MutexPtr instead
+#endif
/** Constructs a new mutex */
static MutexPtr create();
* @param name a name for the object. It is for user-level information and can be nullptr.
* @param code is a function describing the behavior of the process.
* @param data a pointer to any data one may want to attach to the new object. It is for user-level information and
- * can be nullptr. It can be retrieved with the function @ref MSG_process_get_data.
+ * can be nullptr. It can be retrieved with the function MSG_process_get_data().
* @param host the location where the new process is executed.
* @param argc first argument passed to @a code
* @param argv second argument passed to @a code
* @param name a name for the object. It is for user-level information and can be nullptr.
* @param code is a function describing the behavior of the process.
* @param data a pointer to any data one may want to attach to the new object. It is for user-level information and
- * can be nullptr. It can be retrieved with the function @ref MSG_process_get_data.
+ * can be nullptr. It can be retrieved with the function MSG_process_get_data().
* @param host the location where the new process is executed.
* @param argc first argument passed to @a code
* @param argv second argument passed to @a code. WARNING, these strings are freed by the SimGrid kernel when the
* @param message_size a value of the amount of data (in bytes) needed to transfer this new task. If 0, then it cannot
* be transferred with MSG_task_send() and MSG_task_recv(). This value has to be >=0.
* @param data a pointer to any data may want to attach to the new object. It is for user-level information and can
- * be nullptr. It can be retrieved with the function @ref MSG_task_get_data.
+ * be nullptr. It can be retrieved with the function MSG_task_get_data().
* @return The new corresponding object.
*/
msg_task_t MSG_task_create(const char *name, double flop_amount, double message_size, void *data)
* @param bytes_amount an array of @p host_nb* @p host_nb doubles.
* @param data a pointer to any data may want to attach to the new object.
* It is for user-level information and can be nullptr.
- * It can be retrieved with the function @ref MSG_task_get_data().
+ * It can be retrieved with the function MSG_task_get_data().
*/
msg_task_t MSG_parallel_task_create(const char *name, int host_nb, const msg_host_t * host_list,
double *flops_amount, double *bytes_amount, void *data)
* @brief Sets the tracing category of a task.
*
* This function should be called after the creation of a MSG task, to define the category of that task. The
- * first parameter task must contain a task that was =created with the function #MSG_task_create. The second
+ * first parameter task must contain a task that was =created with the function MSG_task_create(). The second
* parameter category must contain a category that was previously declared with the function #TRACE_category
* (or with #TRACE_category_with_color).
*
- * See @ref outcomes_vizu for details on how to trace the (categorized) resource utilization.
+ * @beginrst
+ * See :ref:`outcomes_vizu` for details on how to trace the (categorized) resource utilization.
+ * @endrst
*
* @param task the task that is going to be categorized
* @param category the name of the category to be associated to the task
XBT_LOG_NEW_DEFAULT_SUBCATEGORY(s4u_file, s4u, "S4U files");
int sg_storage_max_file_descriptors = 1024;
-/** @defgroup plugin_filesystem
- @beginrst
-
- @endrst
+/** @defgroup plugin_filesystem Plugin FileSystem
+ *
+ * This adds the notion of Files on top of the storage notion that provided by the core of SimGrid.
+ * Activate this plugin at will.
*/
-
namespace simgrid {
namespace s4u {
simgrid::xbt::Extension<Disk, FileSystemDiskExt> FileSystemDiskExt::EXTENSION_ID;
SIMGRID_REGISTER_PLUGIN(host_energy, "Cpu energy consumption.", &sg_host_energy_plugin_init)
-/** @defgroup plugin_host_energy
+/** @defgroup plugin_host_energy plugin_host_energy Plugin Host Energy
@beginrst
This is the energy plugin, enabling to account not only for computation time, but also for the dissipated energy in the
simulated platform.
-To activate this plugin, first call :cpp:func:`sg_host_energy_plugin_init()` before your :cpp:func:`MSG_init()`, and
-then use :cpp:func:`MSG_host_get_consumed_energy()` to retrieve the consumption of a given host.
+To activate this plugin, first call :cpp:func:`sg_host_energy_plugin_init()` before your loading your platform, and
+then use :cpp:func:`sg_host_get_consumed_energy()` to retrieve the consumption of a given host.
When the host is on, this energy consumption naturally depends on both the current CPU load and the host energy profile.
According to our measurements, the consumption is somehow linear in the amount of cores at full speed, with an
As a result, our energy model takes 4 parameters:
- ``Idle`` wattage (i.e., instantaneous consumption in Watt) when your host is up and running, but without anything to
-do.
+ do.
- ``Epsilon`` wattage when all cores are at 0 or epsilon%, but not in Idle state.
- ``AllCores`` wattage when all cores of the host are at 100%.
- ``Off`` wattage when the host is turned off.
// Makes sure that this plugin can be activated from the command line with ``--cfg=plugin:host_load``
SIMGRID_REGISTER_PLUGIN(host_load, "Cpu load", &sg_host_load_plugin_init)
-/** @defgroup plugin_host_load
+/** @defgroup plugin_host_load Simple plugin that monitors the current load for each host.
@beginrst
-
-Simple plugin that monitors the current load for each host.
-
In addition, this constitutes a good introductory example on how to write a plugin.
It attaches an extension to each host to store some data, and places callbacks in the following signals:
- :cpp:member:`simgrid::s4u::Host::on_creation`: Attach a new extension to the newly created host.
- :cpp:member:`simgrid::s4u::Exec::on_start`: Make note that a new execution started, increasing the load.
- :cpp:member:`simgrid::s4u::Exec::on_completion`: Make note that an execution completed, decreasing the load.
- - :cpp:member:`simgrid::s4u::Host::on_state_change`: Do what is appropriate when the host gets suspended, turned off or similar.
+ - :cpp:member:`simgrid::s4u::Host::on_state_change`: Do what is appropriate when the host gets suspended, turned off
+ or similar.
- :cpp:member:`simgrid::s4u::Host::on_speed_change`: Do what is appropriate when the DVFS is modified.
Note that extensions are automatically destroyed when the host gets destroyed.
SIMGRID_REGISTER_PLUGIN(link_energy, "Link energy consumption.", &sg_link_energy_plugin_init)
-/** @defgroup plugin_link_energy
+/** @defgroup plugin_link_energy Plugin Link Energy
This is the link energy plugin, accounting for the dissipated energy in the simulated platform.
