From ad2e588c6af6cf84b18ba7c1c96f4f9785d93c28 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Paul=20B=C3=A9daride?= Date: Tue, 21 Jan 2014 14:44:07 +0100 Subject: [PATCH] SURF Documentation --- doc/Doxyfile.in | 3 +- doc/doxygen/module-surf.doc | 93 +++- include/simgrid/platf.h | 3 +- src/include/surf/surf.h | 619 +++++++++++++++++++++++++- src/surf/cpu_interface.cpp | 8 +- src/surf/cpu_interface.hpp | 162 ++++++- src/surf/network_interface.cpp | 3 +- src/surf/network_interface.hpp | 166 ++++++- src/surf/plugins/energy.cpp | 20 +- src/surf/storage_interface.hpp | 182 +++++++- src/surf/surf_c_bindings.cpp | 5 +- src/surf/surf_interface.cpp | 91 ++-- src/surf/surf_interface.hpp | 610 ++++++++++++++++++++----- src/surf/surf_private.h | 9 +- src/surf/surf_routing.hpp | 40 +- src/surf/vm_workstation_interface.hpp | 79 +++- src/surf/workstation_interface.cpp | 1 - src/surf/workstation_interface.hpp | 297 +++++++++++- 18 files changed, 2156 insertions(+), 235 deletions(-) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 104b4ee2dc..dde4f8d3fa 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -116,7 +116,7 @@ ALWAYS_DETAILED_SEC = NO # members were ordinary class members. Constructors, destructors and assignment # operators of the base classes will not be shown. -INLINE_INHERITED_MEMB = YES +INLINE_INHERITED_MEMB = NO # If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full # path before files name in the file list and in the header files. If set @@ -699,6 +699,7 @@ INPUT = doxygen/index.doc \ @top_srcdir@/src/include/surf \ @top_srcdir@/src/xbt/ \ @top_srcdir@/src/surf/ \ + @top_srcdir@/src/surf/plugins/ \ @top_srcdir@/src/msg/ \ @top_srcdir@/src/simdag \ @top_srcdir@/src/simix \ diff --git a/doc/doxygen/module-surf.doc b/doc/doxygen/module-surf.doc index a756aef6ae..0ebc5fa292 100644 --- a/doc/doxygen/module-surf.doc +++ b/doc/doxygen/module-surf.doc @@ -1,10 +1,21 @@ /** \addtogroup SURF_API - + \section SURF_doc Surf documentation + Surf is composed several components: - \ref SURF_simulation - \ref SURF_actions - \ref SURF_resources - \ref SURF_build_api + - \ref SURF_interface + - \ref SURF_routing + - \ref SURF_cpu_interface + - \ref SURF_network_interface + - \ref SURF_storage_interface + - \ref SURF_workstation_interface + - \ref SURF_vm_workstation_interface + - \ref SURF_callbacks + - \ref SURF_plugin_energy + */ @@ -83,3 +94,83 @@ we strongly recommand you to contact us before anyway. */ + +/** +@defgroup SURF_c_bindings SURF C bindings +@ingroup SURF_API +@brief Describes the c bindings of SURF + +@htmlonly @endhtmlonly +*/ + +/** +@defgroup SURF_routing_interface SURF Routing Interface +@ingroup SURF_API +@brief Describes the routing interface + +@htmlonly @endhtmlonly +*/ + +/** +@defgroup SURF_interface SURF Interface +@ingroup SURF_API +@brief Describes the general interface for all components (Cpu, Network, Storage, Workstation, WorkstationVM) + +@htmlonly @endhtmlonly +*/ + +/** +@defgroup SURF_cpu_interface SURF Cpu Interface +@ingroup SURF_API +@brief Describes the general Cpu interface for all Cpu implementations + +@htmlonly @endhtmlonly +*/ + +/** +@defgroup SURF_network_interface SURF Network Interface +@ingroup SURF_API +@brief Describes the general Network interface for all Network implementations + +@htmlonly @endhtmlonly +*/ + +/** +@defgroup SURF_storage_interface SURF Storage Interface +@ingroup SURF_API +@brief Describes the general interface for all Storage implementations + +@htmlonly @endhtmlonly +*/ + +/** +@defgroup SURF_workstation_interface SURF Workstation Interface +@ingroup SURF_API +@brief Describes the general interface for all Workstation implementations + +@htmlonly @endhtmlonly +*/ + +/** +@defgroup SURF_vm_workstation_interface SURF VM Workstation Interface +@ingroup SURF_API +@brief Describes the general interface for all VM Workstation implementations + +@htmlonly @endhtmlonly +*/ + +/** +@defgroup SURF_callbacks SURF callbacks +@ingroup SURF_API +@brief Describes how to use the SURF callbacks + +@htmlonly @endhtmlonly +*/ + +/** +@defgroup SURF_plugin_energy SURF Energy Plugin +@ingroup SURF_API +@brief Describes how to use the energy plugin. + +@htmlonly @endhtmlonly +*/ \ No newline at end of file diff --git a/include/simgrid/platf.h b/include/simgrid/platf.h index 20bb10f269..6232a15e9f 100644 --- a/include/simgrid/platf.h +++ b/include/simgrid/platf.h @@ -18,7 +18,8 @@ typedef struct RoutingEdge *sg_routing_edge_t; XBT_PUBLIC(sg_routing_edge_t) sg_routing_edge_by_name_or_null(const char *name); -/** Defines whether a given resource is working or not */ +/** @ingroup SURF_interface +* @brief Defines whether a given resource is working or not */ typedef enum { SURF_RESOURCE_ON = 1, /**< Up & ready */ SURF_RESOURCE_OFF = 0 /**< Down & broken */ diff --git a/src/include/surf/surf.h b/src/include/surf/surf.h index 5499ec562e..162e6108b8 100644 --- a/src/include/surf/surf.h +++ b/src/include/surf/surf.h @@ -149,14 +149,13 @@ XBT_PUBLIC(int) find_model_description(s_surf_model_description_t * table, XBT_PUBLIC(void) model_help(const char *category, s_surf_model_description_t * table); -/** \ingroup SURF_actions - * \brief Action states +/** @ingroup SURF_interface + * @brief Action states * * Action states. * - * \see surf_action_t, surf_action_state_t + * @see Action */ - typedef enum { SURF_ACTION_READY = 0, /**< Ready */ SURF_ACTION_RUNNING, /**< Running */ @@ -167,19 +166,20 @@ typedef enum { /**< Not in the system anymore. Why did you ask ? */ } e_surf_action_state_t; +/** @ingroup SURF_vm_interface + * + * + */ /* FIXME: Where should the VM state be defined? */ typedef enum { - /* created, but not yet started */ - SURF_VM_STATE_CREATED, + SURF_VM_STATE_CREATED, /**< created, but not yet started */ SURF_VM_STATE_RUNNING, SURF_VM_STATE_MIGRATING, - /* Suspend/resume does not involve disk I/O, so we assume there is no transition states. */ - SURF_VM_STATE_SUSPENDED, + SURF_VM_STATE_SUSPENDED, /**< Suspend/resume does not involve disk I/O, so we assume there is no transition states. */ - /* Save/restore involves disk I/O, so there should be transition states. */ - SURF_VM_STATE_SAVING, + SURF_VM_STATE_SAVING, /**< Save/restore involves disk I/O, so there should be transition states. */ SURF_VM_STATE_SAVED, SURF_VM_STATE_RESTORING, @@ -211,91 +211,690 @@ static inline void *surf_storage_resource_by_name(const char *name){ return xbt_lib_get_elm_or_null(storage_lib, name); } + XBT_PUBLIC(char *) surf_routing_edge_name(sg_routing_edge_t edge); XBT_PUBLIC(void *) surf_as_cluster_get_backbone(AS_t as); XBT_PUBLIC(void) surf_as_cluster_set_backbone(AS_t as, void* backbone); + +/** @{ @ingroup SURF_c_bindings */ + +/** + * @brief Get the name of a surf model + * + * @param model A model + * @return The name of the model + */ XBT_PUBLIC(const char *) surf_model_name(surf_model_t model); + +/** + * @brief Pop an action from the done actions set + * + * @param model The model from which the action is extracted + * @return An action in done state + */ XBT_PUBLIC(surf_action_t) surf_model_extract_done_action_set(surf_model_t model); + +/** + * @brief Pop an action from the failed actions set + * + * @param model The model from which the action is extracted + * @return An action in failed state + */ XBT_PUBLIC(surf_action_t) surf_model_extract_failed_action_set(surf_model_t model); + +/** + * @brief Pop an action from the ready actions set + * + * @param model The model from which the action is extracted + * @return An action in ready state + */ XBT_PUBLIC(surf_action_t) surf_model_extract_ready_action_set(surf_model_t model); + +/** + * @brief Pop an action from the running actions set + * + * @param model The model from which the action is extracted + * @return An action in running state + */ XBT_PUBLIC(surf_action_t) surf_model_extract_running_action_set(surf_model_t model); + +/** + * @brief Get the size of the running action set of a model + * + * @param model The model + * @return The size of the running action set + */ XBT_PUBLIC(int) surf_model_running_action_set_size(surf_model_t model); + +/** + * @brief Execute a parallel task + * @details [long description] + * + * @param model The model which handle the parallelisation + * @param workstation_nb The number of workstations + * @param workstation_list The list of workstations on which the task is executed + * @param computation_amount The processing amount (in flop) needed to process + * @param communication_amount The amount of data (in bytes) needed to transfer + * @param rate [description] + * @return The action corresponding to the parallele execution task + */ XBT_PUBLIC(surf_action_t) surf_workstation_model_execute_parallel_task(surf_workstation_model_t model, int workstation_nb, void **workstation_list, double *computation_amount, double *communication_amount, double rate); + +/** + * @brief Create a communication between two hosts + * + * @param model The model which handle the communication + * @param src The source host + * @param dst The destination host + * @param size The amount of data (in bytes) needed to transfer + * @param rate [description] + * @return The action corresponding to the communication + */ XBT_PUBLIC(surf_action_t) surf_workstation_model_communicate(surf_workstation_model_t model, surf_resource_t src, surf_resource_t dst, double size, double rate); + +/** + * @brief Get the route between two hosts + * @details [long description] + * + * @param model The model which handle the routes + * @param src The source host + * @param dst The destination host + * @return The list of [TODO] from the source to the host + */ XBT_PUBLIC(xbt_dynar_t) surf_workstation_model_get_route(surf_workstation_model_t model, surf_resource_t src, surf_resource_t dst); + +/** + * @brief Create a new VM on the specified host + * + * @param name The name of the workstation + * @param ind_phys_host The host on which the VM is created + */ XBT_PUBLIC(void) surf_vm_workstation_model_create(const char *name, surf_resource_t ind_phys_host); + +/** + * @brief Create a communication between two routing edges [TODO] + * @details [long description] + * + * @param model The model which handle the communication + * @param src The source host + * @param dst The destination host + * @param size The amount of data (in bytes) needed to transfer + * @param rate [description] + * @return The action corresponding to the communication + */ XBT_PUBLIC(surf_action_t) surf_network_model_communicate(surf_network_model_t model, sg_routing_edge_t src, sg_routing_edge_t dst, double size, double rate); + +/** + * @brief Get the name of a surf resource (cpu, workstation, network, …) + * + * @param resource The surf resource + * @return The name of the surf resource + */ XBT_PUBLIC(const char * ) surf_resource_name(surf_cpp_resource_t resource); + +/** + * @brief Get the properties of a surf resource (cpu, workstation, network, …) + * + * @param resource The surf resource + * @return The properties of the surf resource + */ XBT_PUBLIC(xbt_dict_t) surf_resource_get_properties(surf_cpp_resource_t resource); + +/** + * @brief Get the state of a surf resource (cpu, workstation, network, …) + * + * @param resource The surf resource + * @return The state of the surf resource + */ XBT_PUBLIC(e_surf_resource_state_t) surf_resource_get_state(surf_cpp_resource_t resource); + +/** + * @brief Set the state of a surf resource (cpu, workstation, network, …) + * + * @param resource The surf resource + * @param state The new state of the surf resource + */ XBT_PUBLIC(void) surf_resource_set_state(surf_cpp_resource_t resource, e_surf_resource_state_t state); + +/** + * @brief Get the speed of the cpu associtated to a workstation + * + * @param resource The surf workstation + * @param load [description] + * + * @return [description] + */ XBT_PUBLIC(double) surf_workstation_get_speed(surf_resource_t resource, double load); + +/** + * @brief Get the available speed of cpu associtated to a workstation + * + * @param resource The surf workstation + * @return [description] + */ XBT_PUBLIC(double) surf_workstation_get_available_speed(surf_resource_t resource); + +/** + * @brief Get the number of cores of the cpu associated to a workstation + * + * @param resource The surf workstation + * @return The number of cores + */ XBT_PUBLIC(int) surf_workstation_get_core(surf_resource_t resource); + +/** + * @brief Execute some quantity of computation + * + * @param resource The surf workstation + * @param size The value of the processing amount (in flop) needed to process + * + * @return The surf action corresponding to the processing + */ XBT_PUBLIC(surf_action_t) surf_workstation_execute(surf_resource_t resource, double size); + +/** + * @brief Make the workstation sleep + * + * @param resource The surf workstation + * @param duration The number of seconds to sleep + * @return The surf action corresponding to the sleep + */ XBT_PUBLIC(surf_action_t) surf_workstation_sleep(surf_resource_t resource, double duration); + +/** + * @brief Open a file on a workstation + * + * @param workstation The surf workstation + * @param mount The mount point + * @param path The path to the file + * @return The surf action corresponding to the openning + */ XBT_PUBLIC(surf_action_t) surf_workstation_open(surf_resource_t workstation, const char* mount, const char* path); + +/** + * @brief Close a file descriptor on a workstation + * + * @param workstation The surf workstation + * @param fd The file descriptor + * + * @return The surf action corresponding to the closing + */ XBT_PUBLIC(surf_action_t) surf_workstation_close(surf_resource_t workstation, surf_file_t fd); + +/** + * @brief Read a file + * + * @param resource The surf workstation + * @param fd The file descriptor to read + * @param size The size in bytes to read + * @return The surf action corresponding to the reading + */ XBT_PUBLIC(surf_action_t) surf_workstation_read(surf_resource_t resource, surf_file_t fd, sg_size_t size); + +/** + * @brief Write a file + * + * @param resource The surf workstation + * @param fd The file descriptor to write + * @param size The size in bytes to write + * @return The surf action corresponding to the writing + */ XBT_PUBLIC(surf_action_t) surf_workstation_write(surf_resource_t resource, surf_file_t fd, sg_size_t size); + +/** + * @brief Get the informations of a file descriptor + * @details The returned xbt_dynar_t contains: + * - the size of the file, + * - the mount point, + * - the storage name, + * - the storage typeId, + * - the storage content type + * + * @param resource The surf workstation + * @param fd The file descriptor + * @return An xbt_dynar_t with the file informations + */ XBT_PUBLIC(xbt_dynar_t) surf_workstation_get_info(surf_resource_t resource, surf_file_t fd); + +/** + * @brief Get the available space of the storage at the mount point + * + * @param resource The surf workstation + * @param name The mount point + * @return The amount of availble space in bytes + */ XBT_PUBLIC(sg_size_t) surf_workstation_get_free_size(surf_resource_t resource, const char* name); + +/** + * @brief Get the used space of the storage at the mount point + * + * @param resource The surf workstation + * @param name The mount point + * @return The amount of used space in bytes + */ XBT_PUBLIC(sg_size_t) surf_workstation_get_used_size(surf_resource_t resource, const char* name); + +/** + * @brief Get the VMs hosted on the workstation + * + * @param resource The surf workstation + * @return The list of VMs on the workstation + */ XBT_PUBLIC(xbt_dynar_t) surf_workstation_get_vms(surf_resource_t resource); + +/** + * @brief [brief description] + * @details [long description] + * + * @param resource [description] + * @param params [description] + */ XBT_PUBLIC(void) surf_workstation_get_params(surf_resource_t resource, ws_params_t params); + +/** + * @brief [brief description] + * @details [long description] + * + * @param resource [description] + * @param params [description] + */ XBT_PUBLIC(void) surf_workstation_set_params(surf_resource_t resource, ws_params_t params); + +/** + * @brief Destroy a Workstation VM + * + * @param resource The surf workstation vm + */ XBT_PUBLIC(void) surf_vm_workstation_destroy(surf_resource_t resource); + +/** + * @brief Suspend a Workstation VM + * + * @param resource The surf workstation vm + */ XBT_PUBLIC(void) surf_vm_workstation_suspend(surf_resource_t resource); + +/** + * @brief Resume a Workstation VM + * + * @param resource The surf workstation vm + */ XBT_PUBLIC(void) surf_vm_workstation_resume(surf_resource_t resource); + +/** + * @brief Save the Workstation VM (Not yet implemented) + * + * @param resource The surf workstation vm + */ XBT_PUBLIC(void) surf_vm_workstation_save(surf_resource_t resource); + +/** + * @brief Restore the Workstation VM (Not yet implemented) + * + * @param resource The surf workstation vm + */ XBT_PUBLIC(void) surf_vm_workstation_restore(surf_resource_t resource); + +/** + * @brief Migrate the VM to the destination host + * + * @param resource The surf workstation vm + * @param ind_vm_ws_dest The destination host + */ XBT_PUBLIC(void) surf_vm_workstation_migrate(surf_resource_t resource, surf_resource_t ind_vm_ws_dest); + +/** + * @brief Get the physical machine hosting the VM + * + * @param resource The surf workstation vm + * @return The physical machine hosting the VM + */ XBT_PUBLIC(surf_resource_t) surf_vm_workstation_get_pm(surf_resource_t resource); + +/** + * @brief [brief description] + * @details [long description] + * + * @param resource [description] + * @param bound [description] + */ XBT_PUBLIC(void) surf_vm_workstation_set_bound(surf_resource_t resource, double bound); + +/** + * @brief [brief description] + * @details [long description] + * + * @param resource [description] + * @param cpu [description] + * @param long [description] + */ XBT_PUBLIC(void) surf_vm_workstation_set_affinity(surf_resource_t resource, surf_resource_t cpu, unsigned long mask); + +/** + * @brief Execute some quantity of computation + * + * @param cpu The surf cpu + * @param size The value of the processing amount (in flop) needed to process + * @return The surf action corresponding to the processing + */ XBT_PUBLIC(surf_action_t) surf_cpu_execute(surf_resource_t cpu, double size); + +/** + * @brief Make the cpu sleep for duration (in seconds) + * @details [long description] + * + * @param cpu The surf cpu + * @param duration The number of seconds to sleep + * @return The surf action corresponding to the sleeping + */ XBT_PUBLIC(surf_action_t) surf_cpu_sleep(surf_resource_t cpu, double duration); + +/** + * @brief Get the workstation power peak + * @details [long description] + * + * @param resource The surf workstation + * @return The power peak + */ XBT_PUBLIC(double) surf_workstation_get_current_power_peak(surf_resource_t host); + +/** + * @brief [brief description] + * @details [long description] + * + * @param resource [description] + * @param pstate_index [description] + * + * @return [description] + */ XBT_PUBLIC(double) surf_workstation_get_power_peak_at(surf_resource_t host, int pstate_index); + +/** + * @brief [brief description] + * @details [long description] + * + * @param resource [description] + * @return [description] + */ XBT_PUBLIC(int) surf_workstation_get_nb_pstates(surf_resource_t host); + +/** + * @brief [brief description] + * @details [long description] + * + * @param resource [description] + * @param pstate_index [description] + */ XBT_PUBLIC(void) surf_workstation_set_power_peak_at(surf_resource_t host, int pstate_index); + +/** + * @brief Get the consumed energy (in joules) of a workstation + * + * @param resource The surf workstation + * @return The consumed energy + */ XBT_PUBLIC(double) surf_workstation_get_consumed_energy(surf_resource_t host); + +/** + * @brief Get the list of storages of a workstation + * + * @param workstation The surf workstation + * @return Dictionary of mount point, Storage + */ XBT_PUBLIC(xbt_dict_t) surf_workstation_get_storage_list(surf_resource_t workstation); + +/** + * @brief Unlink a file descriptor + * + * @param workstation The surf workstation + * @param fd The file descriptor + * + * @return 0 if failed to unlink, 1 otherwise + */ XBT_PUBLIC(int) surf_workstation_unlink(surf_resource_t workstation, surf_file_t fd); + +/** + * @brief List directory contents of a path + * @details [long description] + * + * @param workstation The surf workstation + * @param mount The mount point + * @param path The path to the directory + * @return The surf action corresponding to the ls action + */ XBT_PUBLIC(surf_action_t) surf_workstation_ls(surf_resource_t workstation, const char* mount, const char *path); + +/** + * @brief Get the size of a file on a workstation + * + * @param workstation The surf workstation + * @param fd The file descriptor + * + * @return The size in bytes of the file + */ XBT_PUBLIC(size_t) surf_workstation_get_size(surf_resource_t workstation, surf_file_t fd); + +/** + * @brief Get the current position of the file descriptor + * + * @param workstation The surf workstation + * @param fd The file descriptor + * @return The current position of the file descriptor + */ XBT_PUBLIC(size_t) surf_workstation_file_tell(surf_resource_t workstation, surf_file_t fd); + +/** + * @brief Set the position indictator assiociated with the file descriptor to a new position + * @details [long description] + * + * @param workstation The surf workstation + * @param fd The file descriptor + * @param offset The offset from the origin + * @param origin Position used as a reference for the offset + * - SEEK_SET: beginning of the file + * - SEEK_CUR: current position indicator + * - SEEK_END: end of the file + * @return MSG_OK if successful, otherwise MSG_TASK_CANCELED + */ XBT_PUBLIC(int) surf_workstation_file_seek(surf_resource_t workstation, surf_file_t fd, sg_size_t offset, int origin); + +/** + * @brief [brief description] + * @details [long description] + * + * @param link [description] + * @return [description] + */ XBT_PUBLIC(int) surf_network_link_is_shared(surf_cpp_resource_t link); + +/** + * @brief Get the bandwidth of a link in bytes per second + * + * @param link The surf link + * @return The bandwidth in bytes per second + */ XBT_PUBLIC(double) surf_network_link_get_bandwidth(surf_cpp_resource_t link); + +/** + * @brief Get the latency of a link in seconds + * + * @param link The surf link + * @return The latency in seconds + */ XBT_PUBLIC(double) surf_network_link_get_latency(surf_cpp_resource_t link); + +/** + * @brief Get the content of a storage + * + * @param resource The surf storage + * @return A xbt_dict_t with path as keys and size in bytes as values + */ XBT_PUBLIC(xbt_dict_t) surf_storage_get_content(surf_resource_t resource); + +/** + * @brief Get the size in bytes of a storage + * + * @param resource The surf storage + * @return The size in bytes of the storage + */ XBT_PUBLIC(sg_size_t) surf_storage_get_size(surf_resource_t resource); + +/** + * @brief Rename a path + * + * @param resource The surf storage + * @param src The old path + * @param dest The new path + */ XBT_PUBLIC(void) surf_storage_rename(surf_resource_t resource, const char* src, const char* dest); + +/** + * @brief Get the data associated to the action + * + * @param action The surf action + * @return The data associated to the action + */ XBT_PUBLIC(void*) surf_action_get_data(surf_action_t action); + +/** + * @brief Set the data associated to the action + * @details [long description] + * + * @param action The surf action + * @param data The new data associated to the action + */ XBT_PUBLIC(void) surf_action_set_data(surf_action_t action, void *data); + +/** + * @brief Unreference an action + * + * @param action The surf action + */ XBT_PUBLIC(void) surf_action_unref(surf_action_t action); + +/** + * @brief Get the start time of an action + * + * @param action The surf action + * @return The start time in seconds from the beginning of the simulation + */ XBT_PUBLIC(double) surf_action_get_start_time(surf_action_t action); + +/** + * @brief Get the finish time of an action + * + * @param action The surf action + * @return The finish time in seconds from the beginning of the simulation + */ XBT_PUBLIC(double) surf_action_get_finish_time(surf_action_t action); + +/** + * @brief Get the remains amount of work to do of an action + * + * @param action The surf action + * @return The remains amount of work to do + */ XBT_PUBLIC(double) surf_action_get_remains(surf_action_t action); + +/** + * @brief Suspend an action + * + * @param action The surf action + */ XBT_PUBLIC(void) surf_action_suspend(surf_action_t action); + +/** + * @brief Resume an action + * + * @param action The surf action + */ XBT_PUBLIC(void) surf_action_resume(surf_action_t action); + +/** + * @brief Cancel an action + * + * @param action The surf action + */ XBT_PUBLIC(void) surf_action_cancel(surf_action_t action); + +/** + * @brief Set the priority of an action + * @details [long description] + * + * @param action The surf action + * @param priority The new priority [TODO] + */ XBT_PUBLIC(void) surf_action_set_priority(surf_action_t action, double priority); + +/** + * @brief Set the category of an action + * @details [long description] + * + * @param action The surf action + * @param category The new category of the action + */ XBT_PUBLIC(void) surf_action_set_category(surf_action_t action, const char *category); + +/** + * @brief Get the state of an action + * + * @param action The surf action + * @return The state of the action + */ XBT_PUBLIC(e_surf_action_state_t) surf_action_get_state(surf_action_t action); + +/** + * @brief Get the cost of an action + * + * @param action The surf action + * @return The cost of the action + */ XBT_PUBLIC(int) surf_action_get_cost(surf_action_t action); + +/** + * @brief [brief desrciption] + * @details [long description] + * + * @param action The surf cpu action + * @param cpu [description] + * @param long [description] + */ XBT_PUBLIC(void) surf_cpu_action_set_affinity(surf_action_t action, surf_resource_t cpu, unsigned long mask); + +/** + * @brief [brief description] + * @details [long description] + * + * @param action The surf cpu action + * @param bound [description] + */ XBT_PUBLIC(void) surf_cpu_action_set_bound(surf_action_t action, double bound); + +/** + * @brief Get the file associated to a storage action + * + * @param action The surf storage action + * @return The file associated to a storage action + */ XBT_PUBLIC(surf_file_t) surf_storage_action_get_file(surf_action_t action); + +/** + * @brief Get the result dictionary of an ls action + * + * @param action The surf storage action + * @return The dictionry listing a path + */ XBT_PUBLIC(xbt_dict_t) surf_storage_action_get_ls_dict(surf_action_t action); + XBT_PUBLIC(surf_model_t) surf_resource_model(const void *host, int level); +/** @} */ + /**************************************/ /* Implementations of model object */ /**************************************/ diff --git a/src/surf/cpu_interface.cpp b/src/surf/cpu_interface.cpp index 730f12e67a..a55374be5d 100644 --- a/src/surf/cpu_interface.cpp +++ b/src/surf/cpu_interface.cpp @@ -126,6 +126,10 @@ void CpuModel::updateActionsStateFull(double now, double delta) * Resource * ************/ +Cpu::Cpu(){ + surf_callback_emit(createCpuCallbacks, this); +} + Cpu::Cpu(ModelPtr model, const char *name, xbt_dict_t props, int core, double powerPeak, double powerScale) : Resource(model, name, props) @@ -134,7 +138,9 @@ Cpu::Cpu(ModelPtr model, const char *name, xbt_dict_t props, , m_powerScale(powerScale) , p_constraintCore(NULL) , p_constraintCoreId(NULL) -{surf_callback_emit(createCpuCallbacks, this);} +{ + surf_callback_emit(createCpuCallbacks, this); +} Cpu::Cpu(ModelPtr model, const char *name, xbt_dict_t props, lmm_constraint_t constraint, int core, double powerPeak, double powerScale) diff --git a/src/surf/cpu_interface.hpp b/src/surf/cpu_interface.hpp index 852d71c3a4..7e2c9cda37 100644 --- a/src/surf/cpu_interface.hpp +++ b/src/surf/cpu_interface.hpp @@ -1,3 +1,9 @@ +/* Copyright (c) 2004-2013. The SimGrid Team. + * All rights reserved. */ + +/* This program is free software; you can redistribute it and/or modify it + * under the terms of the license (GNU LGPL) which comes with this package. */ + #include "surf_interface.hpp" #include "maxmin_private.hpp" @@ -24,17 +30,51 @@ typedef CpuPlugin *CpuPluginPtr; *************/ CpuPtr getActionCpu(CpuActionPtr action); +/** @ingroup SURF_callbacks + * @brief Callbacks handler which emit the callbacks after Cpu creation * + * @detail Callback functions have the following signature: `void(CpuPtr)` + */ extern surf_callback(void, CpuPtr) createCpuCallbacks; + +/** @ingroup SURF_callbacks + * @brief Callbacks handler which emit the callbacks after Cpu destruction * + * @detail Callback functions have the following signature: `void(CpuPtr)` + */ extern surf_callback(void, CpuPtr) deleteCpuCallbacks; + +/** @ingroup SURF_callbacks + * @brief Callbacks handler which emit the callbacks after CpuAction update * + * @detail Callback functions have the following signature: `void(CpuActionPtr)` + */ extern surf_callback(void, CpuActionPtr) updateCpuActionCallbacks; /********* * Model * *********/ + + /** @ingroup SURF_cpu_interface + * @brief SURF cpu model interface class + * @details A model is an object which handle the interactions between its Resources and its Actions + */ class CpuModel : public Model { public: + /** + * @brief CpuModel constructor + * + * @param name The name of the model + */ CpuModel(const char *name) : Model(name) {}; + + /** + * @brief Create a Cpu + * + * @param name The name of the Cpu + * + * @return The created Cpu + */ CpuPtr createResource(string name); + + void updateActionsStateLazy(double now, double delta); void updateActionsStateFull(double now, double delta); @@ -44,23 +84,103 @@ public: /************ * Resource * ************/ + +/** @ingroup SURF_cpu_interface +* @brief SURF cpu resource interface class +* @details A Cpu represent a cpu associated to a workstation +*/ class Cpu : public Resource { public: - Cpu(){surf_callback_emit(createCpuCallbacks, this);}; + /** + * @brief Cpu constructor + */ + Cpu(); + + /** + * @brief Cpu constructor + * + * @param model The CpuModel associated to this Cpu + * @param name The name of the Cpu + * @param props Dictionary of properties associated to this Cpu + * @param constraint The lmm constraint associated to this Cpu if it is part of a LMM component + * @param core The number of core of this Cpu + * @param powerPeak The power peak of this Cpu + * @param powerScale The power scale of this Cpu + */ Cpu(ModelPtr model, const char *name, xbt_dict_t props, lmm_constraint_t constraint, int core, double powerPeak, double powerScale); + + /** + * @brief Cpu constructor + * + * @param model The CpuModel associated to this Cpu + * @param name The name of the Cpu + * @param props Dictionary of properties associated to this Cpu + * @param core The number of core of this Cpu + * @param powerPeak The power peak of this Cpu in [TODO] + * @param powerScale The power scale of this Cpu in [TODO] + */ Cpu(ModelPtr model, const char *name, xbt_dict_t props, int core, double powerPeak, double powerScale); + + /** + * @brieaf Cpu destructor + */ ~Cpu(); + + /** + * @brief Execute some quantity of computation + * + * @param size The value of the processing amount (in flop) needed to process + * @return The CpuAction corresponding to the processing + */ virtual CpuActionPtr execute(double size)=0; + + /** + * @brief Make a process sleep for duration (in seconds) + * + * @param duration The number of seconds to sleep + * @return The CpuAction corresponding to the sleeping + */ virtual CpuActionPtr sleep(double duration)=0; + + /** + * @brief Get the number of cores of the current Cpu + * + * @return The number of cores of the current Cpu + */ virtual int getCore(); + + /** + * @brief Get the speed of the current Cpu + * @details [TODO] load * m_powerPeak + * + * @param load [TODO] + * + * @return The speed of the current Cpu + */ virtual double getSpeed(double load); + + /** + * @brief Get the available speed of the current Cpu + * @details [TODO] + * + * @return The available speed of the current Cpu + */ virtual double getAvailableSpeed(); + /** + * @brief Get the current Cpu power peak + * + * @return The current Cpu power peak + */ virtual double getCurrentPowerPeak()=0; + + virtual double getPowerPeakAt(int pstate_index)=0; + virtual int getNbPstates()=0; + virtual void setPowerPeakAt(int pstate_index)=0; void addTraces(void); @@ -76,15 +196,55 @@ public: /********** * Action * **********/ + + /** @ingroup SURF_cpu_interface + * @brief SURF Cpu action interface class + * @details A CpuAction represent the execution of code on a Cpu + */ class CpuAction : public Action { friend CpuPtr getActionCpu(CpuActionPtr action); public: + /** + * @brief CpuAction constructor + */ CpuAction(){}; + + /** + * @brief CpuAction constructor + * + * @param model The CpuModel associated to this CpuAction + * @param cost [TODO] + * @param failed [TODO] + */ CpuAction(ModelPtr model, double cost, bool failed) : Action(model, cost, failed) {} //FIXME:REMOVE + + /** + * @brief CpuAction constructor + * + * @param model The CpuModel associated to this CpuAction + * @param cost [TODO] + * @param failed [TODO] + * @param var The lmm variable associated to this CpuAction if it is part of a LMM component + */ CpuAction(ModelPtr model, double cost, bool failed, lmm_variable_t var) : Action(model, cost, failed, var) {} + + /** + * @brief Set the affinity of the current CpuAction + * @details [TODO] + * + * @param cpu [TODO] + * @param long [TODO] + */ virtual void setAffinity(CpuPtr cpu, unsigned long mask); + + /** + * @brief Set the bound of current CpuAction + * @details [TODO] + * + * @param bound [TODO] + */ virtual void setBound(double bound); void updateRemainingLazy(double now); diff --git a/src/surf/network_interface.cpp b/src/surf/network_interface.cpp index 49103cebbb..bb53714d07 100644 --- a/src/surf/network_interface.cpp +++ b/src/surf/network_interface.cpp @@ -35,7 +35,8 @@ double NetworkModel::bandwidthConstraint(double rate, double /*bound*/, double / } NetworkLink::NetworkLink(NetworkModelPtr model, const char *name, xbt_dict_t props) -: p_latEvent(NULL) +: Resource(model, name, props) +, p_latEvent(NULL) {} NetworkLink::NetworkLink(NetworkModelPtr model, const char *name, xbt_dict_t props, diff --git a/src/surf/network_interface.hpp b/src/surf/network_interface.hpp index fd646bb78f..b9425d2ba0 100644 --- a/src/surf/network_interface.hpp +++ b/src/surf/network_interface.hpp @@ -1,9 +1,9 @@ -/* - * network_interface.hpp - * - * Created on: Nov 29, 2013 - * Author: bedaride - */ +/* Copyright (c) 2004-2013. The SimGrid Team. + * All rights reserved. */ + +/* This program is free software; you can redistribute it and/or modify it + * under the terms of the license (GNU LGPL) which comes with this package. */ + #include "surf_interface.hpp" #include "surf_routing.hpp" @@ -31,14 +31,31 @@ void net_define_callbacks(void); /********* * Model * *********/ +/** @ingroup SURF_network_interface + * @brief SURF network model interface class + * @details A model is an object which handle the interactions between its Resources and its Actions + */ class NetworkModel : public Model { public: + /** + * @brief NetworkModel constructor + */ NetworkModel() : Model("network") { }; + + /** + * @brief NetworkModel constructor + * + * @param name The name of the NetworkModel + */ NetworkModel(const char *name) : Model(name) { f_networkSolve = lmm_solve; m_haveGap = false; }; + + /** + * @brief The destructor of the NetworkModel + */ ~NetworkModel() { if (p_maxminSystem) lmm_system_free(p_maxminSystem); @@ -48,6 +65,20 @@ public: delete p_modifiedSet; } + /** + * @brief Create a NetworkLink + * + * @param name The name of the NetworkLink + * @param bw_initial The initial bandwidth of the NetworkLink in bytes per second + * @param bw_trace The trace associated to the NetworkLink bandwidth [TODO] + * @param lat_initial The initial latency of the NetworkLink in seconds + * @param lat_trace The trace associated to the NetworkLink latency [TODO] + * @param state_initial The initial NetworkLink (state)[e_surf_resource_state_t] + * @param state_trace The trace associated to the NetworkLink (state)[e_surf_resource_state_t] [TODO] + * @param policy The sharing policy of the NetworkLink + * @param properties Dictionary of properties associated to this Resource + * @return The created NetworkLink + */ virtual NetworkLinkPtr createResource(const char *name, double bw_initial, tmgr_trace_t bw_trace, @@ -58,13 +89,67 @@ public: e_surf_link_sharing_policy_t policy, xbt_dict_t properties)=0; + virtual void gapAppend(double /*size*/, const NetworkLinkPtr /*link*/, NetworkActionPtr /*action*/) {}; + + /** + * @brief Create a communication between two [TODO] + * @details [TODO] + * + * @param src The source [TODO] + * @param dst The destination [TODO] + * @param size The size of the communication in bytes + * @param rate The + * @return The action representing the communication + */ virtual ActionPtr communicate(RoutingEdgePtr src, RoutingEdgePtr dst, double size, double rate)=0; + + /** + * @brief Get the route between two RoutingEdge + * @details [TODO] + * + * @param src [TODO] + * @param dst [TODO] + * + * @return A xbt_dynar_t of [TODO] + */ virtual xbt_dynar_t getRoute(RoutingEdgePtr src, RoutingEdgePtr dst); //FIXME: kill field? That is done by the routing nowadays + + /** + * @brief Function pointer to the function to use to solve the lmm_system_t + * + * @param system The lmm_system_t to solve + */ void (*f_networkSolve)(lmm_system_t); + + /** + * @brief [brief description] + * @details [long description] + * + * @param size [description] + * @return [description] + */ virtual double latencyFactor(double size); + + /** + * @brief [brief description] + * @details [long description] + * + * @param size [description] + * @return [description] + */ virtual double bandwidthFactor(double size); + + /** + * @brief [brief description] + * @details [long description] + * + * @param rate [description] + * @param bound [description] + * @param size [description] + * @return [description] + */ virtual double bandwidthConstraint(double rate, double bound, double size); bool m_haveGap; }; @@ -72,17 +157,63 @@ public: /************ * Resource * ************/ - + /** @ingroup SURF_network_interface + * @brief SURF network link interface class + * @details A NetworkLink represent the link between two [Workstations](\ref Workstation) + */ class NetworkLink : public Resource { public: + /** + * @brief NetworkLink constructor + * + * @param model The CpuModel associated to this NetworkLink + * @param name The name of the NetworkLink + * @param props Dictionary of properties associated to this NetworkLink + */ NetworkLink(NetworkModelPtr model, const char *name, xbt_dict_t props); + + /** + * @brief NetworkLink constructor + * + * @param model The CpuModel associated to this NetworkLink + * @param name The name of the NetworkLink + * @param props Dictionary of properties associated to this NetworkLink + * @param constraint The lmm constraint associated to this Cpu if it is part of a LMM component + * @param history [TODO] + * @param state_trace [TODO] + */ NetworkLink(NetworkModelPtr model, const char *name, xbt_dict_t props, lmm_constraint_t constraint, tmgr_history_t history, tmgr_trace_t state_trace); + + /** + * @brief Get the bandwidth in bytes per second of current NetworkLink + * + * @return The bandwith in bytes per second of the current NetworkLink + */ virtual double getBandwidth(); + + /** + * @brief Get the latency in seconds of current NetworkLink + * + * @return The latency in seconds of the current NetworkLink + */ virtual double getLatency(); + + /** + * @brief Check if the NetworkLink is shared + * @details [long description] + * + * @return true if the current NetwokrLink is shared, false otherwise + */ virtual bool isShared(); + + /** + * @brief Check if the NetworkLink is used + * + * @return true if the current NetwokrLink is used, false otherwise + */ bool isUsed(); /* Using this object with the public part of @@ -98,12 +229,33 @@ public: /********** * Action * **********/ +/** @ingroup SURF_network_interface + * @brief SURF network action interface class + * @details A NetworkAction represent a communication bettween two [Workstations](\ref Workstation) + */ class NetworkAction : public Action { public: + /** + * @brief NetworkAction constructor + * + * @param model The NetworkModel associated to this NetworkAction + * @param cost The cost of this NetworkAction in [TODO] + * @param failed [description] + */ NetworkAction(ModelPtr model, double cost, bool failed) : Action(model, cost, failed) {} + + /** + * @brief NetworkAction constructor + * + * @param model The NetworkModel associated to this NetworkAction + * @param cost The cost of this NetworkAction in [TODO] + * @param failed [description] + * @param var The lmm variable associated to this Action if it is part of a LMM component + */ NetworkAction(ModelPtr model, double cost, bool failed, lmm_variable_t var) : Action(model, cost, failed, var) {}; + double m_latency; double m_latCurrent; double m_weight; diff --git a/src/surf/plugins/energy.cpp b/src/surf/plugins/energy.cpp index 9799f52c4f..8719d9cbe4 100644 --- a/src/surf/plugins/energy.cpp +++ b/src/surf/plugins/energy.cpp @@ -1,6 +1,18 @@ +/* Copyright (c) 2010, 2012-2013. The SimGrid Team. + * All rights reserved. */ + +/* This program is free software; you can redistribute it and/or modify it + * under the terms of the license (GNU LGPL) which comes with this package. */ + #include "energy.hpp" #include "../cpu_cas01.hpp" +/** @addtogroup SURF_plugin_energy + * + * + * BlaBla energy + */ + XBT_LOG_EXTERNAL_CATEGORY(surf_kernel); XBT_LOG_NEW_DEFAULT_SUBCATEGORY(surf_energy, surf, "Logging specific to the SURF energy plugin"); @@ -42,7 +54,10 @@ static void updateActionEnergyCallback(CpuActionPtr action){ } } -/* init Energy plugin */ +/** \ingroup SURF_plugin_energy + * \brief Enable energy plugin + * \details Enable energy plugin to get joules consumption of each cpu. + */ void sg_energy_plugin_init() { if (surf_energy == NULL) { surf_energy = new std::map(); @@ -52,6 +67,9 @@ void sg_energy_plugin_init() { } } +/** + * + */ CpuEnergy::CpuEnergy(CpuPtr ptr) : cpu(ptr) { diff --git a/src/surf/storage_interface.hpp b/src/surf/storage_interface.hpp index d11f501f3c..c606e11524 100644 --- a/src/surf/storage_interface.hpp +++ b/src/surf/storage_interface.hpp @@ -1,3 +1,9 @@ +/* Copyright (c) 2004-2013. The SimGrid Team. + * All rights reserved. */ + +/* This program is free software; you can redistribute it and/or modify it + * under the terms of the license (GNU LGPL) which comes with this package. */ + #include "surf_interface.hpp" #ifndef STORAGE_INTERFACE_HPP_ @@ -27,10 +33,32 @@ typedef StorageAction *StorageActionPtr; /********* * Model * *********/ +/** @ingroup SURF_storage_interface + * @brief SURF storage model interface class + * @details A model is an object which handle the interactions between its Resources and its Actions + */ class StorageModel : public Model { public: + /** + * @brief The storage model constructor + */ StorageModel(); + + /** + * @brief The Storange model destructor + */ ~StorageModel(); + + /** + * @brief Create a Storage + * + * @param id [description] + * @param type_id [description] + * @param content_name [description] + * @param content_type [description] + * @param properties [description] + * @return The created Storage + */ virtual StoragePtr createResource(const char* id, const char* type_id, const char* content_name, const char* content_type, xbt_dict_t properties)=0; @@ -40,17 +68,69 @@ public: /************ * Resource * ************/ - +/** @ingroup SURF_storage_interface + * @brief SURF storage interface class + * @details A Storage represent a storage unit (e.g.: hard drive, usb key) + */ class Storage : public Resource { public: + /** + * @brief Storage constructor + * + * @param model StorageModel associated to this Storage + * @param name The name of the Storage + * @param props Dictionary of properties associated to this Storage + * @param constraint The lmm constraint associated to this Storage if it is part of a LMM component + * @param model [description] + * @param name [description] + * @param props [description] + * @param type_id [description] + * @param content_name [description] + * @param content_type [description] + * @param size [description] + */ Storage(ModelPtr model, const char *name, xbt_dict_t props, const char* type_id, char *content_name, char *content_type, sg_size_t size); + + /** + * @brief Storage constructor + * + * @param model StorageModel associated to this Storage + * @param name The name of the Storage + * @param props Dictionary of properties associated to this Storage + * @param constraint The lmm constraint associated to this Storage if it is part of a LMM component + * @param maxminSystem [description] + * @param bread [description] + * @param bwrite [description] + * @param bconnection [description] + * @param type_id [description] + * @param content_name [description] + * @param content_type [description] + * @param size [description] + */ Storage(ModelPtr model, const char *name, xbt_dict_t props, lmm_system_t maxminSystem, double bread, double bwrite, double bconnection, const char* type_id, char *content_name, char *content_type, sg_size_t size); + + /** + * @brief Storage destructor + */ ~Storage(); + /** + * @brief Check if the Storage is used + * + * @return true if the current Storage is used, false otherwise + */ bool isUsed(); + + /** + * @brief Update the state of the current Storage + * + * @param event_type [description] + * @param value [description] + * @param date [description] + */ void updateState(tmgr_trace_event_t event_type, double value, double date); xbt_dict_t p_content; @@ -59,15 +139,71 @@ public: sg_size_t m_usedSize; char * p_typeId; + /** + * @brief Open a file + * + * @param mount The mount point + * @param path The path to the file + * + * @return The StorageAction corresponding to the opening + */ virtual StorageActionPtr open(const char* mount, const char* path)=0; + + /** + * @brief Close a file + * + * @param fd The file descriptor to close + * @return The StorageAction corresponding to the closing + */ virtual StorageActionPtr close(surf_file_t fd)=0; - //virtual StorageActionPtr unlink(surf_file_t fd)=0; + + /** + * @brief List directory contents of a path + * @details [long description] + * + * @param path The path to the directory + * @return The StorageAction corresponding to the ls action + */ virtual StorageActionPtr ls(const char *path)=0; + + /** + * @brief Read a file + * + * @param fd The file descriptor to read + * @param size The size in bytes to read + * @return The StorageAction corresponding to the reading + */ virtual StorageActionPtr read(surf_file_t fd, sg_size_t size)=0; + + /** + * @brief Write a file + * + * @param fd The file descriptor to write + * @param size The size in bytes to write + * @return The StorageAction corresponding to the writing + */ virtual StorageActionPtr write(surf_file_t fd, sg_size_t size)=0; + + /** + * @brief Rename a path + * + * @param src The old path + * @param dest The new path + */ virtual void rename(const char *src, const char *dest)=0; + /** + * @brief Get the content of the current Storage + * + * @return A xbt_dict_t with path as keys and size in bytes as values + */ virtual xbt_dict_t getContent(); + + /** + * @brief Get the size in bytes of the current Storage + * + * @return The size in bytes of the current Storage + */ virtual sg_size_t getSize(); xbt_dict_t parseContent(char *filename); @@ -82,18 +218,52 @@ public: * Action * **********/ +/** @ingroup SURF_storage_interface + * @brief The possible type of action for the storage component + */ typedef enum { - READ=0, WRITE, STAT, OPEN, CLOSE, LS + READ=0, /**< Read a file */ + WRITE, /**< Write in a file */ + STAT, /**< Stat a file */ + OPEN, /**< Open a file */ + CLOSE, /**< Close a file */ + LS /**< List directory contents */ } e_surf_action_storage_type_t; - +/** @ingroup SURF_storage_interface + * @brief SURF storage action interface class + */ class StorageAction : public Action { public: + /** + * @brief StorageAction constructor + */ StorageAction() : m_type(READ) {};//FIXME:REMOVE + + /** + * @brief StorageAction constructor + * + * @param model The StorageModel associated to this StorageAction + * @param cost The cost of this NetworkAction in [TODO] + * @param failed [description] + * @param storage The Storage associated to this StorageAction + * @param type [description] + */ StorageAction(ModelPtr model, double cost, bool failed, - StoragePtr storage, e_surf_action_storage_type_t type); + StoragePtr storage, e_surf_action_storage_type_t type); + + /** + * @brief StorageAction constructor + * + * @param model The StorageModel associated to this StorageAction + * @param cost The cost of this StorageAction in [TODO] + * @param failed [description] + * @param var The lmm variable associated to this StorageAction if it is part of a LMM component + * @param storage The Storage associated to this StorageAction + * @param type [description] + */ StorageAction(ModelPtr model, double cost, bool failed, lmm_variable_t var, - StoragePtr storage, e_surf_action_storage_type_t type); + StoragePtr storage, e_surf_action_storage_type_t type); e_surf_action_storage_type_t m_type; StoragePtr p_storage; diff --git a/src/surf/surf_c_bindings.cpp b/src/surf/surf_c_bindings.cpp index f085ec98c0..be2220250a 100644 --- a/src/surf/surf_c_bindings.cpp +++ b/src/surf/surf_c_bindings.cpp @@ -230,6 +230,7 @@ surf_action_t surf_model_extract_done_action_set(surf_model_t model){ model->getDoneActionSet()->pop_front(); return res; } + surf_action_t surf_model_extract_failed_action_set(surf_model_t model){ if (model->getFailedActionSet()->empty()) return NULL; @@ -237,6 +238,7 @@ surf_action_t surf_model_extract_failed_action_set(surf_model_t model){ model->getFailedActionSet()->pop_front(); return res; } + surf_action_t surf_model_extract_ready_action_set(surf_model_t model){ if (model->getReadyActionSet()->empty()) return NULL; @@ -244,6 +246,7 @@ surf_action_t surf_model_extract_ready_action_set(surf_model_t model){ model->getReadyActionSet()->pop_front(); return res; } + surf_action_t surf_model_extract_running_action_set(surf_model_t model){ if (model->getRunningActionSet()->empty()) return NULL; @@ -539,5 +542,3 @@ surf_file_t surf_storage_action_get_file(surf_action_t action){ xbt_dict_t surf_storage_action_get_ls_dict(surf_action_t action){ return static_cast(action)->p_lsDict; } - - diff --git a/src/surf/surf_interface.cpp b/src/surf/surf_interface.cpp index 0f1c0eae1c..206e8e0238 100644 --- a/src/surf/surf_interface.cpp +++ b/src/surf/surf_interface.cpp @@ -1,3 +1,9 @@ +/* Copyright (c) 2004-2013. The SimGrid Team. + * All rights reserved. */ + +/* This program is free software; you can redistribute it and/or modify it + * under the terms of the license (GNU LGPL) which comes with this package. */ + #include "surf_private.h" #include "surf_interface.hpp" #include "network_interface.hpp" @@ -459,14 +465,14 @@ void surf_exit(void) NOW = 0; /* Just in case the user plans to restart the simulation afterward */ } + /********* * Model * *********/ Model::Model(const char *name) - : p_name(name), p_maxminSystem(0), - m_resOnCB(0), m_resOffCB(0), - m_actCancelCB(0), m_actSuspendCB(0), m_actResumeCB(0) + : p_name(name) + , p_maxminSystem(NULL) { p_readyActionSet = new ActionList(); p_runningActionSet = new ActionList(); @@ -575,12 +581,10 @@ double Model::shareResourcesFull(double /*now*/) { THROW_UNIMPLEMENTED; } - double Model::shareResourcesMaxMin(ActionListPtr running_actions, lmm_system_t sys, void (*solve) (lmm_system_t)) { - void *_action = NULL; ActionPtr action = NULL; double min = -1; double value = -1; @@ -644,66 +648,12 @@ void Model::updateActionsState(double now, double delta) void Model::updateActionsStateLazy(double /*now*/, double /*delta*/) { - } void Model::updateActionsStateFull(double /*now*/, double /*delta*/) { - -} - - -void Model::addTurnedOnCallback(ResourceCallback rc) -{ - m_resOnCB = rc; -} - -void Model::notifyResourceTurnedOn(ResourcePtr r) -{ - m_resOnCB(r); -} - -void Model::addTurnedOffCallback(ResourceCallback rc) -{ - m_resOffCB = rc; -} - -void Model::notifyResourceTurnedOff(ResourcePtr r) -{ - m_resOffCB(r); -} - -void Model::addActionCancelCallback(ActionCallback ac) -{ - m_actCancelCB = ac; -} - -void Model::notifyActionCancel(ActionPtr a) -{ - m_actCancelCB(a); -} - -void Model::addActionResumeCallback(ActionCallback ac) -{ - m_actResumeCB = ac; -} - -void Model::notifyActionResume(ActionPtr a) -{ - m_actResumeCB(a); -} - -void Model::addActionSuspendCallback(ActionCallback ac) -{ - m_actSuspendCB = ac; -} - -void Model::notifyActionSuspend(ActionPtr a) -{ - m_actSuspendCB(a); } - /************ * Resource * ************/ @@ -727,6 +677,11 @@ Resource::Resource(surf_model_t model, const char *name, xbt_dict_t props, e_sur , m_running(true), m_stateCurrent(stateInit) {} +Resource::~Resource() { + xbt_free((void*)p_name); + xbt_dict_free(&p_properties); +} + e_surf_resource_state_t Resource::getState() { return m_stateCurrent; @@ -746,7 +701,6 @@ void Resource::turnOn() { if (!m_running) { m_running = true; - getModel()->notifyResourceTurnedOn(this); } } @@ -754,10 +708,25 @@ void Resource::turnOff() { if (m_running) { m_running = false; - getModel()->notifyResourceTurnedOff(this); } } +ModelPtr Resource::getModel() { + return p_model; +} + +const char *Resource::getName() { + return p_name; +} + +xbt_dict_t Resource::getProperties() { + return p_properties; +} + +lmm_constraint_t Resource::getConstraint() { + return p_constraint; +} + /********** * Action * **********/ diff --git a/src/surf/surf_interface.hpp b/src/surf/surf_interface.hpp index e9cda2590d..cd55b2aaf9 100644 --- a/src/surf/surf_interface.hpp +++ b/src/surf/surf_interface.hpp @@ -1,4 +1,8 @@ -//using namespace generic; +/* Copyright (c) 2004-2013. The SimGrid Team. + * All rights reserved. */ + +/* This program is free software; you can redistribute it and/or modify it + * under the terms of the license (GNU LGPL) which comes with this package. */ #ifndef SURF_MODEL_H_ #define SURF_MODEL_H_ @@ -35,12 +39,6 @@ extern tmgr_history_t history; using namespace std; -/** \ingroup SURF_simulation - * \brief Return the current time - * - * Return the current time in millisecond. - */ - /********* * Utils * *********/ @@ -75,11 +73,9 @@ typedef Model* ModelPtr; //class Resource; typedef Resource* ResourcePtr; -typedef boost::function ResourceCallback; //class Action; typedef Action* ActionPtr; -typedef boost::function ActionCallback; typedef boost::intrusive::list ActionList; typedef ActionList* ActionListPtr; @@ -114,119 +110,276 @@ XBT_PUBLIC_DATA(xbt_dict_t) trace_connect_list_latency; *********/ XBT_PUBLIC_DATA(xbt_dynar_t) model_list; +/** @ingroup SURF_interface + * @brief SURF model interface class + * @details A model is an object which handle the interactions between its Resources and its Actions + */ class Model { - const char *p_name; - - ActionListPtr p_readyActionSet; /**< Actions in state SURF_ACTION_READY */ - ActionListPtr p_runningActionSet; /**< Actions in state SURF_ACTION_RUNNING */ - ActionListPtr p_failedActionSet; /**< Actions in state SURF_ACTION_FAILED */ - ActionListPtr p_doneActionSet; /**< Actions in state SURF_ACTION_DONE */ - - ResourceCallback m_resOnCB, m_resOffCB; - ActionCallback m_actCancelCB, m_actSuspendCB, m_actResumeCB; - -protected: - ActionLmmListPtr p_modifiedSet; - - lmm_system_t p_maxminSystem; - e_UM_t p_updateMechanism; - int m_selectiveUpdate; - xbt_heap_t p_actionHeap; - public: + /** + * @brief Model constructor + * + * @param name the name of the model + */ Model(const char *name); + + /** + * @brief Model destructor + */ virtual ~Model(); + /** + * @brief Get the name of the current Model + * + * @return The name of the current Model + */ const char *getName() {return p_name;} + + /** + * @brief Get the set of [actions](@ref Action) in *ready* state + * + * @return The set of [actions](@ref Action) in *ready* state + */ virtual ActionListPtr getReadyActionSet() {return p_readyActionSet;} + + /** + * @brief Get the set of [actions](@ref Action) in *running* state + * + * @return The set of [actions](@ref Action) in *running* state + */ virtual ActionListPtr getRunningActionSet() {return p_runningActionSet;} + + /** + * @brief Get the set of [actions](@ref Action) in *failed* state + * + * @return The set of [actions](@ref Action) in *failed* state + */ virtual ActionListPtr getFailedActionSet() {return p_failedActionSet;} + + /** + * @brief Get the set of [actions](@ref Action) in *done* state + * + * @return The set of [actions](@ref Action) in *done* state + */ virtual ActionListPtr getDoneActionSet() {return p_doneActionSet;} + + /** + * @brief Get the set of modified [actions](@ref Action) + * + * @return The set of modified [actions](@ref Action) + */ virtual ActionLmmListPtr getModifiedSet() {return p_modifiedSet;} + + /** + * @brief Get the maxmin system of the current Model + * + * @return The maxmin system of the current Model + */ lmm_system_t getMaxminSystem() {return p_maxminSystem;} + + /** + * @brief Get the update mechanism of the current Model + * @see e_UM_t + * + * @return [description] + */ e_UM_t getUpdateMechanism() {return p_updateMechanism;} + + /** + * @brief Get Action heap + * @details [TODO] + * + * @return The Action heap + */ xbt_heap_t getActionHeap() {return p_actionHeap;} - ActionPtr createAction(double _cost, bool _failed); + /** + * @brief share the resources + * @details Share the resources between the actions + * + * @param + * @return the date of the next action will finish + */ virtual double shareResources(double now); virtual double shareResourcesLazy(double now); virtual double shareResourcesFull(double now); double shareResourcesMaxMin(ActionListPtr running_actions, lmm_system_t sys, void (*solve) (lmm_system_t)); + + /** + * @brief Update state of actions + * @details [TODO] + * + * @param now [TODO] + * @param delta [TODO] + */ virtual void updateActionsState(double now, double delta); virtual void updateActionsStateLazy(double now, double delta); virtual void updateActionsStateFull(double now, double delta); - void addTurnedOnCallback(ResourceCallback rc); - void notifyResourceTurnedOn(ResourcePtr r); +protected: + ActionLmmListPtr p_modifiedSet; + lmm_system_t p_maxminSystem; + e_UM_t p_updateMechanism; + int m_selectiveUpdate; + xbt_heap_t p_actionHeap; - void addTurnedOffCallback(ResourceCallback rc); - void notifyResourceTurnedOff(ResourcePtr r); +private: + const char *p_name; - void addActionCancelCallback(ActionCallback ac); - void notifyActionCancel(ActionPtr a); - void addActionResumeCallback(ActionCallback ac); - void notifyActionResume(ActionPtr a); - void addActionSuspendCallback(ActionCallback ac); - void notifyActionSuspend(ActionPtr a); + ActionListPtr p_readyActionSet; /**< Actions in state SURF_ACTION_READY */ + ActionListPtr p_runningActionSet; /**< Actions in state SURF_ACTION_RUNNING */ + ActionListPtr p_failedActionSet; /**< Actions in state SURF_ACTION_FAILED */ + ActionListPtr p_doneActionSet; /**< Actions in state SURF_ACTION_DONE */ }; /************ * Resource * ************/ -/** - * Resource which have a metric handled by a maxmin system +/** @ingroup SURF_interface + * @brief Resource which have a metric handled by a maxmin system */ typedef struct { - double scale; - double peak; - tmgr_trace_event_t event; + double scale; /**< The scale of the metric */ + double peak; /**< The peak of the metric */ + tmgr_trace_event_t event; /**< The associated trace event associated to the metric */ } s_surf_metric_t; +/** @ingroup SURF_interface + * @brief SURF resource interface class + * @details A resource represent an element of a component (e.g.: a link for the network) + */ class Resource { - void *p_resource; - const char *p_name; - ModelPtr p_model; - xbt_dict_t p_properties; - bool m_running; - -protected: - e_surf_resource_state_t m_stateCurrent; - public: + /** + * @brief Resource constructor + */ Resource(); + + /** + * @brief Resource constructor + * + * @param model Model associated to this Resource + * @param name The name of the Resource + * @param props Dictionary of properties associated to this Resource + */ Resource(ModelPtr model, const char *name, xbt_dict_t props); - Resource(ModelPtr model, const char *name, xbt_dict_t props, lmm_constraint_t constraint); - Resource(ModelPtr model, const char *name, xbt_dict_t props, e_surf_resource_state_t stateInit); - Resource(ModelPtr model, const char *name, xbt_dict_t props, e_surf_resource_state_t stateInit, lmm_constraint_t constraint); - virtual ~Resource() { - xbt_free((void*)p_name); - xbt_dict_free(&p_properties); - }; + /** + * @brief Resource constructor + * + * @param model Model associated to this Resource + * @param name The name of the Resource + * @param props Dictionary of properties associated to this Resource + * @param constraint The lmm constraint associated to this Resource if it is part of a LMM component + */ + Resource(ModelPtr model, const char *name, xbt_dict_t props, lmm_constraint_t constraint); - ModelPtr getModel() {return p_model;}; - const char *getName() {return p_name;}; - virtual xbt_dict_t getProperties() {return p_properties;}; + /** + * @brief Resource constructor + * + * @param model Model associated to this Resource + * @param name The name of the Resource + * @param props Dictionary of properties associated to this Resource + * @param stateInit the initial state of the Resource + */ + Resource(ModelPtr model, const char *name, xbt_dict_t props, e_surf_resource_state_t stateInit); + /** + * @brief Resource destructor + */ + virtual ~Resource(); + + /** + * @brief Get the Model of the current Resource + * + * @return The Model of the current Resource + */ + ModelPtr getModel(); + + /** + * @brief Get the name of the current Resource + * + * @return The name of the current Resource + */ + const char *getName(); + + /** + * @brief Get the properties of the current Resource + * + * @return The properties of the current Resource + */ + virtual xbt_dict_t getProperties(); + + /** + * @brief Update the state of the current Resource + * @details [TODO] + * + * @param event_type [TODO] + * @param value [TODO] + * @param date [TODO] + */ virtual void updateState(tmgr_trace_event_t event_type, double value, double date)=0; + + /** + * @brief Check if the current Resource is used + * @return true if the current Resource is used, false otherwise + */ virtual bool isUsed()=0; + + /** + * @brief Check if the current Resource is active + * + * @return true if the current Resource is active, false otherwise + */ bool isOn(); + + /** + * @brief Turn on the current Resource + */ void turnOn(); + + /** + * @brief Turn off the current Resource + */ void turnOff(); - void setName(string name); + /** + * @brief Get the [state](\ref e_surf_resource_state_t) of the current Resource + * + * @return The state of the currenrt Resource + */ virtual e_surf_resource_state_t getState(); + + /** + * @brief Set the [state](\ref e_surf_resource_state_t) of the current Resource + * + * @param state The new state of the current Resource + */ virtual void setState(e_surf_resource_state_t state); +protected: + e_surf_resource_state_t m_stateCurrent; + +private: + ModelPtr p_model; + const char *p_name; + xbt_dict_t p_properties; + void *p_resource; + bool m_running; + /* LMM */ +public: + /** + * @brief Get the lmm constraint associated to this Resource if it is part of a LMM component + * + * @return The lmm constraint associated to this Resource + */ + lmm_constraint_t getConstraint(); private: lmm_constraint_t p_constraint; -public: - lmm_constraint_t getConstraint() {return p_constraint;}; - }; /********** @@ -234,102 +387,313 @@ public: **********/ void surf_action_lmm_update_index_heap(void *action, int i); +/** @ingroup SURF_interface + * @brief SURF action interface class + * @details An action is an event generated by a resource (e.g.: a communication for the network) + */ class Action : public actionHook, public actionLmmHook { - ActionLmmListPtr p_modifiedSet; - xbt_heap_t p_actionHeap; - int m_selectiveUpdate; - ModelPtr p_model; - double m_bound; /**< the capping of the CPU use */ - bool m_failed; - double m_start; /**< start time */ - char *p_category; /**< tracing category for categorized resource utilization monitoring */ - - #ifdef HAVE_LATENCY_BOUND_TRACKING - int m_latencyLimited; /**< Set to 1 if is limited by latency, 0 otherwise */ - #endif - int m_cost; - void *p_data; /**< for your convenience */ - -protected: - ActionListPtr p_stateSet; - double m_priority; /**< priority (1.0 by default) */ - int m_refcount; - double m_remains; /**< How much of that cost remains to be done in the currently running task */ - double m_maxDuration; /*< max_duration (may fluctuate until the task is completed) */ - double m_finish; /**< finish time : this is modified during the run and fluctuates until the task is completed */ - - ModelPtr getModel() {return p_model;} - public: - + /** + * @brief Action constructor + */ Action(); + + /** + * @brief Action constructor + * + * @param model The Model associated to this Action + * @param cost The cost of the Action + * @param failed If the action is impossible (e.g.: execute something on a switched off workstation) + */ Action(ModelPtr model, double cost, bool failed); + + /** + * @brief Action constructor + * + * @param model The Model associated to this Action + * @param cost The cost of the Action + * @param failed If the action is impossible (e.g.: execute something on a switched off workstation) + * @param var The lmm variable associated to this Action if it is part of a LMM component + */ Action(ModelPtr model, double cost, bool failed, lmm_variable_t var); + + /** + * @brief Action destructor + */ virtual ~Action(); + /** + * @brief Finish the action + */ void finish(); - s_xbt_swag_hookup_t p_stateHookup; + /** + * @brief Get the [state](\ref e_surf_action_state_t) of the current Action + * + * @return The state of the current Action + */ e_surf_action_state_t getState(); /**< get the state*/ + + /** + * @brief Set the [state](\ref e_surf_action_state_t) of the current Action + * + * @param state The new state of the current Action + */ virtual void setState(e_surf_action_state_t state); /**< Change state*/ + + /** + * @brief Get the bound of the current Action + * + * @return The bound of the current Action + */ double getBound() {return m_bound;} - double getStartTime(); /**< Return the start time of an action */ - double getFinishTime(); /**< Return the finish time of an action */ + + /** + * @brief Get the start time of the current action + * + * @return The start time of the current action + */ + double getStartTime(); + + /** + * @brief Get the finish time of the current action + * + * @return The finish time of the current action + */ + double getFinishTime(); + + /** + * @brief Get the data associated to the current action + * + * @return The data associated to the current action + */ void *getData() {return p_data;} + + /** + * @brief Set the data associated to the current action + * + * @param data The new data associated to the current action + */ void setData(void* data); + + /** + * @brief Get the maximum duration of the current action + * + * @return The maximum duration of the current action + */ double getMaxDuration() {return m_maxDuration;} + + /** + * @brief Get the category associated to the current action + * + * @return The category associated to the current action + */ char *getCategory() {return p_category;} + + /** + * @brief Get the cost of the current action + * + * @return The cost of the current action + */ double getCost() {return m_cost;} + + /** + * @brief Set the cost of the current action + * + * @param cost The new cost of the current action + */ void setCost(double cost) {m_cost = cost;} + /** + * @brief Update the maximum duration of the current action + * + * @param delta [TODO] + */ void updateMaxDuration(double delta) {double_update(&m_maxDuration, delta);} + + /** + * @brief Update the remaining time of the current action + * + * @param delta [TODO] + */ void updateRemains(double delta) {double_update(&m_remains, delta);} + + /** + * @brief Set the remaining time of the current action + * + * @param value The new remaining time of the current action + */ void setRemains(double value) {m_remains = value;} - void setFinishTime(double value) {m_finish = value;} + /** + * @brief Set the finish time of the current action + * + * @param value The new Finush time of the current action + */ + void setFinishTime(double value) {m_finish = value;} + /** + * @brief Add a reference to the current action + */ void ref(); - virtual int unref(); /**< Specify that we don't use that action anymore. Returns true if the action was destroyed and false if someone still has references on it. */ - virtual void cancel(); /**< Cancel a running action */ - virtual void recycle(){}; /**< Recycle an action */ - - virtual void suspend(); /**< Suspend an action */ - virtual void resume(); /**< Resume a suspended action */ - virtual bool isSuspended(); /**< Return whether an action is suspended */ - virtual void setMaxDuration(double duration); /**< Set the max duration of an action*/ - virtual void setPriority(double priority); /**< Set the priority of an action */ + + /** + * @brief Remove a reference to the current action + * @details If the Action has no more reference, we destroy it + * + * @return true if the action was destroyed and false if someone still has references on it + */ + virtual int unref(); + + /** + * @brief Cancel the current Action if running + */ + virtual void cancel(); + + /** + * @brief Recycle an Action + */ + virtual void recycle(){}; + + /** + * @brief Suspend the current Action + */ + virtual void suspend(); + + /** + * @brief Resume the current Action + */ + virtual void resume(); + + /** + * @brief Check if the current action is running + * + * @return true if the current Action is suspended, false otherwise + */ + virtual bool isSuspended(); + + /** + * @brief Set the maximum duration of the current Action + * + * @param duration The new maximum duration of the current Action + */ + virtual void setMaxDuration(double duration); + + /** + * @brief Set the priority of the current Action + * + * @param priority The new priority of the current Action + */ + virtual void setPriority(double priority); + #ifdef HAVE_TRACING - void setCategory(const char *category); /**< Set the category of an action */ + /** + * @brief Set the category of the current Action + * + * @param category The new category of the current Action + */ + void setCategory(const char *category); #endif - virtual double getRemains(); /**< Get the remains of an action */ + + /** + * @brief Get the remaining time of the current action after updating the resource + * + * @return The remaining time + */ + virtual double getRemains(); + + /** + * @brief Get the remaining time of the current action without updating the resource + * + * @return The remaining time + */ double getRemainsNoUpdate(); #ifdef HAVE_LATENCY_BOUND_TRACKING - int getLatencyLimited(); /**< Return 1 if action is limited by latency, 0 otherwise */ + /** + * @brief Check if the action is limited by latency. + * + * @return 1 if action is limited by latency, 0 otherwise + */ + int getLatencyLimited(); #endif + /** + * @brief Get the priority of the current Action + * + * @return The priority of the current Action + */ double getPriority() {return m_priority;}; + + /** + * @brief Get the state set in which the action is + * @details [TODO] + * + * @return The state set in which the action is + */ ActionListPtr getStateSet() {return p_stateSet;}; + s_xbt_swag_hookup_t p_stateHookup; + +protected: + ActionListPtr p_stateSet; + double m_priority; /**< priority (1.0 by default) */ + int m_refcount; + double m_remains; /**< How much of that cost remains to be done in the currently running task */ + double m_maxDuration; /*< max_duration (may fluctuate until the task is completed) */ + double m_finish; /**< finish time : this is modified during the run and fluctuates until the task is completed */ + + ModelPtr getModel() {return p_model;} + private: int resourceUsed(void *resource_id); - /* Share the resources to the actions and return in how much time - the next action may terminate */ + + /** + * @brief Share the resources to the actions + * @details [TODO] + * + * @param now [TODO] + * @return in how much time the next action may terminatedescription] + */ double shareResources(double now); - /* Update the actions' state */ + + /** + * @brief Update the current action state + * @details [TODO] + * + * @param now [TODO] + * @param delta [TODO] + */ void updateActionsState(double now, double delta); + + /** + * @brief Update the [TODO] + * @details [TODO] + * + * @param id [TODO] + * @param event_type [TODO] + * @param value [TODO] + * @param time [TODO] + */ void updateResourceState(void *id, tmgr_trace_event_t event_type, double value, double time); - /* LMM */ -protected: - lmm_variable_t p_variable; - double m_lastUpdate; - double m_lastValue; - int m_suspended; - int m_indexHeap; - enum heap_action_type m_hat; + ActionLmmListPtr p_modifiedSet; + xbt_heap_t p_actionHeap; + int m_selectiveUpdate; + ModelPtr p_model; + double m_bound; /**< the capping of the CPU use */ + bool m_failed; + double m_start; /**< start time */ + char *p_category; /**< tracing category for categorized resource utilization monitoring */ + #ifdef HAVE_LATENCY_BOUND_TRACKING + int m_latencyLimited; /**< Set to 1 if is limited by latency, 0 otherwise */ + #endif + int m_cost; + void *p_data; /**< for your convenience */ + + /* LMM */ public: virtual void updateRemainingLazy(double now); void heapInsert(xbt_heap_t heap, double key, enum heap_action_type hat); @@ -341,6 +705,14 @@ public: enum heap_action_type getHat() {return m_hat;} bool is_linked() {return actionLmmHook::is_linked();} void gapRemove(); + +protected: + lmm_variable_t p_variable; + double m_lastUpdate; + double m_lastValue; + int m_suspended; + int m_indexHeap; + enum heap_action_type m_hat; }; #endif /* SURF_MODEL_H_ */ diff --git a/src/surf/surf_private.h b/src/surf/surf_private.h index f2a889ccf5..25a2102c89 100644 --- a/src/surf/surf_private.h +++ b/src/surf/surf_private.h @@ -23,10 +23,13 @@ extern xbt_dict_t watched_hosts_lib; extern const char *surf_action_state_names[6]; +/** @ingroup SURF_interface + * @brief Possible update mechanisms + */ typedef enum { - UM_FULL, - UM_LAZY, - UM_UNDEFINED + UM_FULL, /**< [TODO] */ + UM_LAZY, /**< [TODO] */ + UM_UNDEFINED /**< Mechanism not defined */ } e_UM_t; /* Generic functions common to all models */ diff --git a/src/surf/surf_routing.hpp b/src/surf/surf_routing.hpp index 8c2c90f9a5..5a1de77adb 100644 --- a/src/surf/surf_routing.hpp +++ b/src/surf/surf_routing.hpp @@ -14,13 +14,13 @@ xbt_edge_t new_xbt_graph_edge (xbt_graph_t graph, xbt_node_t s, xbt_node_t d, xb /*********** * Classes * ***********/ -struct As; +class As; typedef As *AsPtr; class RoutingModelDescription; typedef RoutingModelDescription *RoutingModelDescriptionPtr; -struct RoutingEdge; +class RoutingEdge; typedef RoutingEdge *RoutingEdgePtr; class Onelink; @@ -29,7 +29,11 @@ typedef Onelink *OnelinkPtr; class RoutingPlatf; typedef RoutingPlatf *RoutingPlatfPtr; -struct As { +/** @ingroup SURF_routing_interface + * @brief The Autonomous System (AS) routing interface + * @details [TODO] + */ +class As { public: xbt_dynar_t p_indexNetworkElm; xbt_dict_t p_bypassRoutes; /* store bypass routes */ @@ -41,11 +45,27 @@ public: RoutingEdgePtr p_netElem; xbt_dynar_t p_linkUpDownList; + /** + * @brief The As constructor + */ As(){}; + + /** + * @brief The As destructor + */ virtual ~As(){ xbt_free(p_name); }; + /** + * @brief Get the route and latency between two RoutingEdgs + * @details [long description] + * + * @param src [description] + * @param dst [description] + * @param into [description] + * @param latency [description] + */ virtual void getRouteAndLatency(RoutingEdgePtr src, RoutingEdgePtr dst, sg_platf_route_cbarg_t into, double *latency)=0; virtual xbt_dynar_t getOneLinkRoutes()=0; virtual void getGraph(xbt_graph_t graph, xbt_dict_t nodes, xbt_dict_t edges)=0; @@ -62,7 +82,11 @@ public: virtual void parseBypassroute(sg_platf_route_cbarg_t e_route)=0; }; -struct RoutingEdge { +/** @ingroup SURF_routing_interface + * @brief A routing edge + * @details [long description] + */ +class RoutingEdge { public: ~RoutingEdge() { xbt_free(p_name);}; AsPtr p_rcComponent; @@ -71,8 +95,9 @@ public: char *p_name; }; -/* - * Link of lenght 1, alongside with its source and destination. This is mainly usefull in the bindings to gtnets and ns3 + +/** @ingroup SURF_routing_interface + * @brief Link of lenght 1, alongside with its source and destination. This is mainly usefull in the bindings to gtnets and ns3 */ class Onelink { public: @@ -83,6 +108,9 @@ public: void *p_link; }; +/** @ingroup SURF_routing_interface + * @brief The class representing a whole routing platform + */ class RoutingPlatf { public: ~RoutingPlatf(); diff --git a/src/surf/vm_workstation_interface.hpp b/src/surf/vm_workstation_interface.hpp index 7217b9f0b9..ec334ac5b5 100644 --- a/src/surf/vm_workstation_interface.hpp +++ b/src/surf/vm_workstation_interface.hpp @@ -1,9 +1,9 @@ -/* - * vm_workstation.hpp - * - * Created on: Nov 12, 2013 - * Author: bedaride - */ +/* Copyright (c) 2004-2013. The SimGrid Team. + * All rights reserved. */ + +/* This program is free software; you can redistribute it and/or modify it + * under the terms of the license (GNU LGPL) which comes with this package. */ + #include "workstation_interface.hpp" #ifndef VM_WORKSTATION_INTERFACE_HPP_ @@ -30,12 +30,32 @@ typedef WorkstationVMLmm *WorkstationVMLmmPtr; /********* * Model * *********/ - +/** @ingroup SURF_vm_workstation_interface + * @brief SURF workstation VM model interface class + * @details A model is an object which handle the interactions between its Resources and its Actions + */ class WorkstationVMModel : public WorkstationModel { public: + /** + * @brief WorkstationVMModel consrtuctor + */ WorkstationVMModel(); + + /** + * @brief WorkstationVMModel consrtuctor + */ ~WorkstationVMModel(){}; + + /** + * @brief Create a new WorkstationVM + * + * @param name The name of the new WorkstationVM + * @param ind_phys_workstation The workstation hosting the VM + * + */ virtual void createResource(const char *name, void *ind_phys_workstation)=0; + + void adjustWeightOfDummyCpuActions() {}; }; @@ -43,22 +63,62 @@ public: * Resource * ************/ +/** @ingroup SURF_vm_workstation_interface + * @brief SURF workstation VM interface class + * @details A workstation VM represent an virtual machine + */ class WorkstationVM : public Workstation { public: + /** + * @brief WorkstationVM consrtructor + * + * @param model WorkstationModel associated to this Workstation + * @param name The name of the Workstation + * @param props Dictionary of properties associated to this Workstation + * @param netElm The RoutingEdge associated to this Workstation + * @param cpu The Cpu associated to this Workstation + */ WorkstationVM(ModelPtr model, const char *name, xbt_dict_t props, RoutingEdgePtr netElm, CpuPtr cpu) : Workstation(model, name, props, NULL, netElm, cpu) {} + + /** + * @brief WdorkstationVM estructor + */ ~WorkstationVM(); + /** + * @brief Suspend the VM + */ virtual void suspend()=0; + + /** + * @brief Resume the VM + */ virtual void resume()=0; + /** + * @brief Save the VM (Not yet implemented) + */ virtual void save()=0; + + /** + * @brief Restore the VM (Not yet implemented) + */ virtual void restore()=0; - virtual void migrate(surf_resource_t ind_vm_ws_dest)=0; // will be vm_ws_migrate() + /** + * @brief Migrate the VM to the destination host + * + * @param ind_vm_ws_dest The destination host + */ + virtual void migrate(surf_resource_t ind_vm_ws_dest)=0; - virtual surf_resource_t getPm()=0; // will be vm_ws_get_pm() + /** + * @brief Get the physical machine hosting the VM + * @return The physical machine hosting the VM + */ + virtual surf_resource_t getPm()=0; virtual void setBound(double bound)=0; virtual void setAffinity(CpuPtr cpu, unsigned long mask)=0; @@ -69,7 +129,6 @@ public: e_surf_vm_state_t p_currentState; }; - /********** * Action * **********/ diff --git a/src/surf/workstation_interface.cpp b/src/surf/workstation_interface.cpp index 92dd79ea21..9af820b2d2 100644 --- a/src/surf/workstation_interface.cpp +++ b/src/surf/workstation_interface.cpp @@ -128,7 +128,6 @@ xbt_dict_t Workstation::getProperties() return p_cpu->getProperties(); } - StoragePtr Workstation::findStorageOnMountList(const char* mount) { StoragePtr st = NULL; diff --git a/src/surf/workstation_interface.hpp b/src/surf/workstation_interface.hpp index cf5f66dff2..5045cec283 100644 --- a/src/surf/workstation_interface.hpp +++ b/src/surf/workstation_interface.hpp @@ -1,3 +1,9 @@ +/* Copyright (c) 2004-2013. The SimGrid Team. + * All rights reserved. */ + +/* This program is free software; you can redistribute it and/or modify it + * under the terms of the license (GNU LGPL) which comes with this package. */ + #include "surf_interface.hpp" #include "storage_interface.hpp" #include "cpu_interface.hpp" @@ -27,19 +33,73 @@ extern WorkstationModelPtr surf_workstation_model; /********* * Model * *********/ +/** @ingroup SURF_workstation_interface + * @brief SURF Workstation model interface class + * @details A model is an object which handle the interactions between its Resources and its Actions + */ class WorkstationModel : public Model { public: + /** + * @brief WorkstationModel constructor + * + * @param name the name of the model + */ WorkstationModel(const char *name); + + /** + * @brief WorkstationModel constructor + */ WorkstationModel(); + + /** + * @brief WorkstationModel destructor + */ ~WorkstationModel(); - virtual void adjustWeightOfDummyCpuActions(); + /** + * @brief [brief description] + * @details [long description] + */ + virtual void adjustWeightOfDummyCpuActions(); + + /** + * @brief [brief description] + * @details [long description] + * + * @param workstation_nb [description] + * @param workstation_list [description] + * @param computation_amount [description] + * @param communication_amount [description] + * @param rate [description] + * @return [description] + */ virtual ActionPtr executeParallelTask(int workstation_nb, void **workstation_list, double *computation_amount, double *communication_amount, double rate)=0; + + /** + * @brief [brief description] + * @details [long description] + * + * @param src [description] + * @param dst [description] + * + * @return [description] + */ virtual xbt_dynar_t getRoute(WorkstationPtr src, WorkstationPtr dst)=0; + + /** + * @brief [brief description] + * @details [long description] + * + * @param src [description] + * @param dst [description] + * @param size [description] + * @param rate [description] + * @return [description] + */ virtual ActionPtr communicate(WorkstationPtr src, WorkstationPtr dst, double size, double rate)=0; CpuModelPtr p_cpuModel; @@ -48,41 +108,235 @@ public: /************ * Resource * ************/ - +/** @ingroup SURF_workstation_interface + * @brief SURF Workstation interface class + * @details A workstation VM represent an virtual machine with a aggregation of a Cpu, a NetworkLink and a Storage + */ class Workstation : public Resource { public: + /** + * @brief Workstation consrtuctor + * @details [long description] + */ Workstation(){}; + + /** + * @brief Workstation constructor + * + * @param model WorkstationModel associated to this Workstation + * @param name The name of the Workstation + * @param props Dictionary of properties associated to this Workstation + * @param storage The Storage associated to this Workstation + * @param netElm The RoutingEdge associated to this Workstation + * @param cpu The Cpu associated to this Workstation + */ Workstation(ModelPtr model, const char *name, xbt_dict_t props, xbt_dynar_t storage, RoutingEdgePtr netElm, CpuPtr cpu); + + /** + * @brief Workstation constructor + * + * @param model WorkstationModel associated to this Workstation + * @param name The name of the Workstation + * @param props Dictionary of properties associated to this Workstation + * @param constraint The lmm constraint associated to this Workstation if it is part of a LMM component + * @param storage The Storage associated to this Workstation + * @param netElm The RoutingEdge associated to this Workstation + * @param cpu The Cpu associated to this Workstation + */ Workstation(ModelPtr model, const char *name, xbt_dict_t props, lmm_constraint_t constraint, xbt_dynar_t storage, RoutingEdgePtr netElm, CpuPtr cpu); + /** + * @brief Get the properties of the currenrt Workstation + * + * @return The properties of the current Workstation + */ xbt_dict_t getProperties(); + /** + * @brief Execute some quantity of computation + * + * @param size The value of the processing amount (in flop) needed to process + * @return The CpuAction corresponding to the processing + * @see Cpu + */ virtual ActionPtr execute(double size)=0; + + /** + * @brief Make a process sleep for duration seconds + * + * @param duration The number of seconds to sleep + * @return The CpuAction corresponding to the sleeping + * @see Cpu + */ virtual ActionPtr sleep(double duration)=0; + /** + * @brief Get the number of cores of the associated Cpu + * + * @return The number of cores of the associated Cpu + * @see Cpu + */ virtual int getCore(); + + /** + * @brief Get the speed of the associated Cpu + * + * @param load [TODO] + * @return The speed of the associated Cpu + * @see Cpu + */ virtual double getSpeed(double load); + + /** + * @brief Get the available speed of the associated Cpu + * @details [TODO] + * + * @return The available speed of the associated Cpu + * @see Cpu + */ virtual double getAvailableSpeed(); + + /** + * @brief Get the associated Cpu power peak + * + * @return The associated Cpu power peak + * @see Cpu + */ virtual double getCurrentPowerPeak(); + virtual double getPowerPeakAt(int pstate_index); virtual int getNbPstates(); virtual void setPowerPeakAt(int pstate_index); + /** + * @brief Return the storage of corresponding mount point + * + * @param storage The mount point + * @return The corresponding Storage + */ virtual StoragePtr findStorageOnMountList(const char* storage); + + /** + * @brief Get the xbt_dict_t of mount_point: Storage + * + * @return The xbt_dict_t of mount_point: Storage + */ virtual xbt_dict_t getStorageList(); + + /** + * @brief Open a file + * + * @param mount The mount point + * @param path The path to the file + * + * @return The StorageAction corresponding to the opening + */ virtual ActionPtr open(const char* mount, const char* path); + + /** + * @brief Close a file + * + * @param fd The file descriptor to close + * @return The StorageAction corresponding to the closing + */ virtual ActionPtr close(surf_file_t fd); + + /** + * @brief Unlink a file + * @details [long description] + * + * @param fd [description] + * @return [description] + */ virtual int unlink(surf_file_t fd); + + /** + * @brief List directory contents of a path + * @details [long description] + * + * @param path The path to the directory + * @return The StorageAction corresponding to the ls action + */ virtual ActionPtr ls(const char* mount, const char *path); + + /** + * @brief Get the size in bytes of the file + * + * @param fd The file descriptor to read + * @return The size in bytes of the file + */ virtual sg_size_t getSize(surf_file_t fd); + + /** + * @brief Read a file + * + * @param fd The file descriptor to read + * @param size The size in bytes to read + * @return The StorageAction corresponding to the reading + */ virtual ActionPtr read(surf_file_t fd, sg_size_t size); + + /** + * @brief Write a file + * + * @param fd The file descriptor to write + * @param size The size in bytes to write + * @return The StorageAction corresponding to the writing + */ virtual ActionPtr write(surf_file_t fd, sg_size_t size); - virtual xbt_dynar_t getInfo( surf_file_t fd); + + /** + * @brief Get the informations of a file descriptor + * @details The returned xbt_dynar_t contains: + * - the size of the file, + * - the mount point, + * - the storage name, + * - the storage typeId, + * - the storage content type + * + * @param fd The file descriptor + * @return An xbt_dynar_t with the file informations + */ + virtual xbt_dynar_t getInfo(surf_file_t fd); + + /** + * @brief Get the current position of the file descriptor + * + * @param fd The file descriptor + * @return The current position of the file descriptor + */ virtual sg_size_t fileTell(surf_file_t fd); + + /** + * @brief Get the available space of the storage at the mount point + * + * @param name The mount point + * @return The amount of availble space in bytes + */ virtual sg_size_t getFreeSize(const char* name); + + /** + * @brief Get the used space of the storage at the mount point + * + * @param name The mount point + * @return The amount of used space in bytes + */ virtual sg_size_t getUsedSize(const char* name); + + /** + * @brief Set the position indictator assiociated with the file descriptor to a new position + * @details [long description] + * + * @param fd The file descriptor + * @param offset The offset from the origin + * @param origin Position used as a reference for the offset + * - SEEK_SET: beginning of the file + * - SEEK_CUR: current position indicator + * - SEEK_END: end of the file + * @return MSG_OK if successful, otherwise MSG_TASK_CANCELED + */ virtual int fileSeek(surf_file_t fd, sg_size_t offset, int origin); xbt_dynar_t p_storage; @@ -90,10 +344,28 @@ public: CpuPtr p_cpu; NetworkLinkPtr p_network; + /** + * @brief Get the list of virtual machines on the current Workstation + * + * @return The list of VMs + */ xbt_dynar_t getVms(); /* common with vm */ + /** + * @brief [brief description] + * @details [long description] + * + * @param params [description] + */ void getParams(ws_params_t params); + + /** + * @brief [brief description] + * @details [long description] + * + * @param params [description] + */ void setParams(ws_params_t params); s_ws_params_t p_params; }; @@ -101,10 +373,29 @@ public: /********** * Action * **********/ +/** @ingroup SURF_workstation_interface + * @brief SURF workstation action interface class + */ class WorkstationAction : public Action { public: + /** + * @brief WorkstationAction constructor + * + * @param model The WorkstationModel associated to this WorkstationAction + * @param cost The cost of this WorkstationAction in [TODO] + * @param failed [description] + */ WorkstationAction(ModelPtr model, double cost, bool failed) : Action(model, cost, failed) {} + + /** + * @brief WorkstationAction constructor + * + * @param model The WorkstationModel associated to this WorkstationAction + * @param cost The cost of this WorkstationAction in [TODO] + * @param failed [description] + * @param var The lmm variable associated to this StorageAction if it is part of a LMM component + */ WorkstationAction(ModelPtr model, double cost, bool failed, lmm_variable_t var) : Action(model, cost, failed, var) {} -- 2.20.1