From: Martin Quinson Date: Thu, 11 Oct 2018 20:12:41 +0000 (+0200) Subject: Merge branch 'master' of github.com:simgrid/simgrid X-Git-Tag: v3_22~909 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/93c7b4bd9208b45b5a5899abd1da65262431c33f?hp=717bb82fd56727b8a066418eaa654290373736ea Merge branch 'master' of github.com:simgrid/simgrid --- diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 46cc216d9c..7fb6664470 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -20,7 +20,7 @@ with the full power of C++. This is the preferred interface to describe abstract algorithms in the domains of Cloud, P2P, HPC, IoT, and similar settings. -Currently (v3.21), S4U is definitely the way to go for long-term +Since v3.20 (June 2018), 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 diff --git a/include/simgrid/host.h b/include/simgrid/host.h index e75e509845..d65ace35fb 100644 --- a/include/simgrid/host.h +++ b/include/simgrid/host.h @@ -12,21 +12,18 @@ SG_BEGIN_DECL() /** @brief Host datatype. - @ingroup m_host_management - - A location (or host) is any possible place where an actor may run. Thus it is represented as a - physical resource with computing capabilities, some mailboxes to enable running actors to - communicate with remote ones, and some private data that can be only accessed by local actors. + * + * A location (or host) is any possible place where an actor may run. Thus it is represented as a + * physical resource with computing capabilities, some mailboxes to enable running actors to + * communicate with remote ones, and some private data 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,22 +79,17 @@ 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_host_management - * @brief Returns the current computation load (in flops per second). +/** @brief Returns the current computation load (in flops per second). * @param host a host */ XBT_PUBLIC double sg_host_load(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 the current 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 */ diff --git a/include/simgrid/msg.h b/include/simgrid/msg.h index 7db7b0492b..87b46fcff9 100644 --- a/include/simgrid/msg.h +++ b/include/simgrid/msg.h @@ -155,6 +155,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 code with some private data. + * Processes must be located on hosts (#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); @@ -261,8 +269,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 @@ -425,7 +432,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 diff --git a/src/msg/msg_process.cpp b/src/msg/msg_process.cpp index 643e190fa3..e7c6961eee 100644 --- a/src/msg/msg_process.cpp +++ b/src/msg/msg_process.cpp @@ -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 code with some private data. - * Processes must be located on hosts (#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);