Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
doxygen: kill group m_process_management
authorMartin Quinson <martin.quinson@loria.fr>
Wed, 10 Oct 2018 22:56:11 +0000 (00:56 +0200)
committerMartin Quinson <martin.quinson@loria.fr>
Wed, 10 Oct 2018 22:56:11 +0000 (00:56 +0200)
include/simgrid/host.h
include/simgrid/msg.h
src/msg/msg_process.cpp

index 4a72056..9c81a53 100644 (file)
 
 SG_BEGIN_DECL()
 /** @brief Host datatype.
-    @ingroup m_host_management
-
-    A <em>location</em> (or <em>host</em>) is any possible place where an actor may run. Thus it is represented as a
-    <em>physical resource with computing capabilities</em>, some <em>mailboxes</em> to enable running actors to
-    communicate with remote ones, and some <em>private data</em> that can be only accessed by local actors.
+ *
+ *   A <em>location</em> (or <em>host</em>) is any possible place where an actor may run. Thus it is represented as a
+ *   <em>physical resource with computing capabilities</em>, some <em>mailboxes</em> to enable running actors to
+ *   communicate with remote ones, and some <em>private data</em> that can be only accessed by local actors.
  */
 
 XBT_PUBLIC sg_host_t* sg_host_list();
 
-/** @ingroup m_host_management
- * @brief Return the current number of hosts.
- */
+/** @brief Return the current number of hosts. */
 XBT_PUBLIC size_t sg_host_count();
 
-/** @ingroup m_host_management
+/**
  * @brief Return a dynar containing all the hosts declared at a given point of time (including VMs)
  * @remark The host order in the returned array is generally different from the host creation/declaration order in the
  *         XML platform (we use a hash table internally)
@@ -36,8 +33,7 @@ XBT_PUBLIC xbt_dynar_t sg_hosts_as_dynar();
 XBT_PUBLIC size_t sg_host_extension_create(void (*deleter)(void*));
 XBT_PUBLIC void* sg_host_extension_get(sg_host_t host, size_t rank);
 
-/** @ingroup m_host_management
- * @brief Finds a sg_host_t using its name.
+/** @brief Finds a sg_host_t using its name.
  *
  * This is a name directory service
  * @param name the name of an host.
@@ -45,22 +41,16 @@ XBT_PUBLIC void* sg_host_extension_get(sg_host_t host, size_t rank);
  */
 XBT_PUBLIC sg_host_t sg_host_by_name(const char* name);
 
-/** @ingroup m_host_management
- *
- * @brief Return the name of the #sg_host_t. */
+/** @brief Return the name of the #sg_host_t. */
 XBT_PUBLIC const char* sg_host_get_name(sg_host_t host);
 
 // ========== User Data ==============
-/** @ingroup m_host_management
- *
- * @brief Return the user data of a #sg_host_t.
+/** @brief Return the user data of a #sg_host_t.
  *
  * This functions returns the user data associated to @a host if it is possible.
  */
 XBT_PUBLIC void* sg_host_user(sg_host_t host);
-/** @ingroup m_host_management
- *
- * @brief Set the user data of a #sg_host_t.
+/** @brief Set the user data of a #sg_host_t.
  *
  * This functions attach @a data to @a host if it is possible.
  */
@@ -68,24 +58,20 @@ XBT_PUBLIC void sg_host_user_set(sg_host_t host, void* userdata);
 XBT_PUBLIC void sg_host_user_destroy(sg_host_t host);
 
 // ========= storage related functions ============
-/** @ingroup m_host_management
- * @brief Return the list of mount point names on an host.
+/** @brief Return the list of mount point names on an host.
  * @param host a host
  * @return a dict containing all mount point on the host (mount_name => sg_storage_t)
  */
 XBT_PUBLIC xbt_dict_t sg_host_get_mounted_storage_list(sg_host_t host);
 
-/** @ingroup m_host_management
- * @brief Return the list of storages attached to an host.
+/** @brief Return the list of storages attached to an host.
  * @param host a host
  * @return a dynar containing all storages (name) attached to the host
  */
 XBT_PUBLIC xbt_dynar_t sg_host_get_attached_storage_list(sg_host_t host);
 
 // =========== user-level functions ===============
-/** @ingroup m_host_management
- * @brief Return the speed of the processor (in flop/s), regardless of the current load on the machine.
- */
+/** @brief Return the speed of the processor (in flop/s), regardless of the current load on the machine. */
 XBT_PUBLIC double sg_host_speed(sg_host_t host);
 XBT_PUBLIC double sg_host_get_pstate_speed(sg_host_t host, int pstate_index);
 
@@ -93,16 +79,14 @@ XBT_PUBLIC double sg_host_get_available_speed(sg_host_t host);
 
 XBT_PUBLIC int sg_host_core_count(sg_host_t host);
 
-/** @ingroup m_process_management
- * @brief Return the location on which a process is running.
- * @return the sg_host_t corresponding to the location on which @a process is running.
+/** @brief Return the location on which a process is running.
+ *  @return the sg_host_t corresponding to the location on which @a process is running.
  */
 XBT_PUBLIC sg_host_t sg_host_self();
 
 XBT_PUBLIC const char* sg_host_self_get_name();
 
-/** @ingroup m_host_management
- * @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. See also @ref plugin_energy.
  *
  * @param  host host to test
  */
index a62ed6f..b0e67ba 100644 (file)
@@ -154,6 +154,14 @@ XBT_PUBLIC sg_size_t MSG_storage_read(msg_storage_t storage, sg_size_t size);
 XBT_PUBLIC sg_size_t MSG_storage_write(msg_storage_t storage, sg_size_t size);
 
 /* ******************************** Actor/process *************************** */
+/** Processes are independent agents that can do stuff on their own.
+ *  They are in charge of executing your code interacting with the simulated world.
+ *  A process may be defined as a <em>code</em> with some <em>private data</em>.
+ *  Processes must be located on <em>hosts</em> (#msg_host_t), and they exchange data by sending tasks (#msg_task_t)
+ *  that are similar to envelops containing data.
+ *
+ *  @hideinitializer
+ */
 typedef sg_actor_t msg_process_t;
 
 XBT_PUBLIC int MSG_process_get_PID(msg_process_t process);
@@ -260,8 +268,7 @@ typedef enum {
  * MSG_config("host/model","ptask_L07");
  */
 XBT_PUBLIC void MSG_config(const char* key, const char* value);
-/** @ingroup msg_simulation
- *  @brief Initialize the MSG internal data.
+/** @brief Initialize the MSG internal data.
  *  @hideinitializer
  *
  *  It also check that the link-time and compile-time versions of SimGrid do
@@ -424,7 +431,6 @@ XBT_PUBLIC const char* MSG_task_get_category(msg_task_t task);
 XBT_PUBLIC void MSG_mailbox_set_async(const char* alias);
 
 /** @brief Opaque type representing a semaphore
- *  @ingroup msg_synchro
  *  @hideinitializer
  */
 typedef struct s_smx_sem_t* msg_sem_t; // Yeah that's a rename of the smx_sem_t which doesnt require smx_sem_t to be
index 643e190..e7c6961 100644 (file)
@@ -16,15 +16,6 @@ std::string instr_pid(msg_process_t proc)
   return std::string(proc->get_cname()) + "-" + std::to_string(proc->get_pid());
 }
 
-/** @addtogroup m_process_management
- *
- *  Processes (#msg_process_t) are independent agents that can do stuff on their own. They are in charge of executing
- *  your code interacting with the simulated world.
- *  A process may be defined as a <em>code</em> with some <em>private data</em>.
- *  Processes must be located on <em>hosts</em> (#msg_host_t), and they exchange data by sending tasks (#msg_task_t)
- *  that are similar to envelops containing data.
- */
-
 /******************************** Process ************************************/
 /**
  * @brief Cleans the MSG data of an actor
@@ -60,16 +51,12 @@ msg_process_t MSG_process_create(const char *name, xbt_main_func_t code, void *d
   return MSG_process_create_with_environment(name == nullptr ? "" : name, code, data, host, 0, nullptr, nullptr);
 }
 
-/** @brief Creates and runs a new #msg_process_t.
+/** @brief Creates and runs a new process.
 
  * A constructor for #msg_process_t taking four arguments and returning the corresponding object. The structure (and
  * the corresponding thread) is created, and put in the list of ready process.
  * @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. It should then only use functions described
- * in @ref m_process_management (to create a new #msg_process_t for example),
-   in @ref m_host_management (only the read-only functions i.e. whose name contains the word get),
-   in @ref m_task_management (to create or destroy some #msg_task_t for example) and
-   in @ref msg_task_usage (to handle file transfers and task processing).
+ * @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.
  * @param host the location where the new process is executed.
@@ -83,17 +70,13 @@ msg_process_t MSG_process_create_with_arguments(const char *name, xbt_main_func_
   return MSG_process_create_with_environment(name, code, data, host, argc, argv, nullptr);
 }
 
-/** @ingroup m_process_management
+/**
  * @brief Creates and runs a new #msg_process_t.
 
  * A constructor for #msg_process_t taking four arguments and returning the corresponding object. The structure (and
  * the corresponding thread) is created, and put in the list of ready process.
  * @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. It should then only use functions described
- * in @ref m_process_management (to create a new #msg_process_t for example),
-   in @ref m_host_management (only the read-only functions i.e. whose name contains the word get),
-   in @ref m_task_management (to create or destroy some #msg_task_t for example) and
-   in @ref msg_task_usage (to handle file transfers and task processing).
+ * @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.
  * @param host the location where the new process is executed.
@@ -166,7 +149,7 @@ msg_process_t MSG_process_attach(const char *name, void *data, msg_host_t host,
   return process->ciface();
 }
 
-/** Detach a process attached with `MSG_process_attach()`
+/** @brief Detach a process attached with `MSG_process_attach()`
  *
  *  This is called when the current process has finished its job.
  *  Used in the main thread, it waits for the simulation to finish before  returning. When it returns, the other
@@ -177,8 +160,7 @@ void MSG_process_detach()
   SIMIX_process_detach();
 }
 
-/** @ingroup m_process_management
- * @brief Returns the user data of a process.
+/** @brief Returns the user data of a process.
  *
  * This function checks whether @a process is a valid pointer and returns the user data associated to this process.
  */
@@ -190,8 +172,7 @@ void* MSG_process_get_data(msg_process_t process)
   return process->get_impl()->get_user_data();
 }
 
-/** @ingroup m_process_management
- * @brief Sets the user data of a process.
+/** @brief Sets the user data of a process.
  *
  * This function checks whether @a process is a valid pointer and sets the user data associated to this process.
  */
@@ -204,8 +185,7 @@ msg_error_t MSG_process_set_data(msg_process_t process, void *data)
   return MSG_OK;
 }
 
-/** @ingroup m_process_management
- * @brief Sets a cleanup function to be called to free the userdata of a process when a process is destroyed.
+/** @brief Sets a cleanup function to be called to free the userdata of a process when a process is destroyed.
  * @param data_cleanup a cleanup function for the userdata of a process, or nullptr to call no function
  */
 XBT_PUBLIC void MSG_process_set_data_cleanup(void_f_pvoid_t data_cleanup)
@@ -229,8 +209,7 @@ int MSG_process_get_number()
   return SIMIX_process_count();
 }
 
-/** @ingroup m_process_management
- * @brief Return the PID of the current process.
+/** @brief Return the PID of the current process.
  *
  * This function returns the PID of the currently running #msg_process_t.
  */
@@ -240,8 +219,7 @@ int MSG_process_self_PID()
   return self == nullptr ? 0 : self->pid_;
 }
 
-/** @ingroup m_process_management
- * @brief Return the PPID of the current process.
+/** @brief Return the PPID of the current process.
  *
  * This function returns the PID of the parent of the currently running #msg_process_t.
  */
@@ -250,16 +228,13 @@ int MSG_process_self_PPID()
   return MSG_process_get_PPID(MSG_process_self());
 }
 
-/** @ingroup m_process_management
- * @brief Return the name of the current process.
- */
+/** @brief Return the name of the current process. */
 const char* MSG_process_self_name()
 {
   return SIMIX_process_self_get_name();
 }
 
-/** @ingroup m_process_management
- * @brief Return the current process.
+/** @brief Return the current process.
  *
  * This function returns the currently running #msg_process_t.
  */
@@ -271,26 +246,20 @@ msg_process_t MSG_process_self()
 smx_context_t MSG_process_get_smx_ctx(msg_process_t process) { // deprecated -- smx_context_t should die afterward
   return process->get_impl()->context_;
 }
-/**
- * @ingroup m_process_management
- * @brief Add a function to the list of "on_exit" functions for the current process.
- * The on_exit functions are the functions executed when your process is killed.
- * You should use them to free the data used by your process.
+/** @brief Add a function to the list of "on_exit" functions for the current process.
+ *  The on_exit functions are the functions executed when your process is killed.
+ *  You should use them to free the data used by your process.
  */
 void MSG_process_on_exit(int_f_pvoid_pvoid_t fun, void *data) {
   simgrid::s4u::this_actor::on_exit([fun](int a, void* b) { fun((void*)(intptr_t)a, b); }, data);
 }
 
-/** @ingroup m_process_management
- * @brief Take an extra reference on that process to prevent it to be garbage-collected
- */
+/** @brief Take an extra reference on that process to prevent it to be garbage-collected */
 XBT_PUBLIC void MSG_process_ref(msg_process_t process)
 {
   intrusive_ptr_add_ref(process);
 }
-/** @ingroup m_process_management
- * @brief Release a reference on that process so that it can get be garbage-collected
- */
+/** @brief Release a reference on that process so that it can get be garbage-collected */
 XBT_PUBLIC void MSG_process_unref(msg_process_t process)
 {
   intrusive_ptr_release(process);