X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/ab4213398ecc52ebe7bcf337e43bb85cc30dedf3..7b13238bee59da3e8d3621560943d14d18ceeea4:/docs/source/app_s4u.rst diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 2e292a8ec1..268f30c353 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -64,60 +64,60 @@ Virtual machines can also be migrated between hosts. The :ref:`simgrid::s4u::this_actor ` namespace provides many helper functions to simplify the code of actors. -- **Global Classes** +- **Simulation Elements** - - :ref:`class s4u::Actor `: + - :ref:`class Actor `: Active entities executing your application. - - :ref:`class s4u::Engine ` + - :ref:`class Engine ` Simulation engine (singleton). - - :ref:`class s4u::Mailbox ` - Communication rendez-vous. + - :ref:`class Mailbox ` + Communication rendez-vous, with which actors meet each other. -- **Platform Elements** +- **Resources** - - :ref:`class s4u::Disk ` + - :ref:`class Disk ` Resource on which actors can write and read data. - - :ref:`class s4u::Host `: + - :ref:`class Host `: Actor location, providing computational power. - - :ref:`class s4u::Link ` + - :ref:`class Link ` Interconnecting hosts. - - :ref:`class s4u::NetZone `: + - :ref:`class NetZone `: Sub-region of the platform, containing resources (Hosts, Links, etc). - - :ref:`class s4u::VirtualMachine `: + - :ref:`class VirtualMachine `: Execution containers that can be moved between Hosts. -- **Activities** (:ref:`class s4u::Activity `): +- **Activities** (:ref:`class Activity `): The things that actors can do on resources - - :ref:`class s4u::Comm ` + - :ref:`class Comm ` Communication activity, started on Mailboxes and consuming links. - - :ref:`class s4u::Exec ` + - :ref:`class Exec ` Computation activity, started on Host and consuming CPU resources. - - :ref:`class s4u::Io ` + - :ref:`class Io ` I/O activity, started on and consumming disks. -- **Synchronization Mechanisms**: Classical IPC that actors can use +- **Synchronization Objects**: Classical IPC that actors can use - - :ref:`class s4u::Barrier ` - - :ref:`class s4u::ConditionVariable ` - - :ref:`class s4u::Mutex ` - - :ref:`class s4u::Semaphore ` + - :ref:`class Barrier ` + - :ref:`class ConditionVariable ` + - :ref:`class Mutex ` + - :ref:`class Semaphore ` .. |API_s4u_Actors| replace:: **Actors** -.. _API_s4u_Actors: #s4u-actor +.. _API_s4u_Actors: #api-s4u-actor .. |API_s4u_Activities| replace:: **Activities** -.. _API_s4u_Activities: #s4u-activity +.. _API_s4u_Activities: #api-s4u-activity .. |API_s4u_Hosts| replace:: **Hosts** -.. _API_s4u_Hosts: #s4u-host +.. _API_s4u_Hosts: #api-s4u-host .. |API_s4u_Links| replace:: **Links** -.. _API_s4u_Links: #s4u-link +.. _API_s4u_Links: #api-s4u-link .. |API_s4u_Disks| replace:: **Disks** -.. _API_s4u_Disks: #s4u-disk +.. _API_s4u_Disks: #api-s4u-disk .. |API_s4u_VirtualMachine| replace:: **VirtualMachines** @@ -138,12 +138,16 @@ provides many helper functions to simplify the code of actors. .. |API_s4u_Mutex| replace:: **Mutex** +.. _s4u_Activities: + Activities ********** Activities represent the actions that consume a resource, such as a -:ref:`s4u::Comm ` that consumes the *transmitting power* of -:ref:`s4u::Link ` resources. +:ref:`Comm ` that consumes the *transmitting power* of +:ref:`Link ` resources, or an :ref:`Exec ` +that consumes the *computing power* of :ref:`Host ` resources. +See also the :ref:`full API ` below. ======================= Asynchronous Activities @@ -334,6 +338,8 @@ that marked as permanent receiver, you should call memory gets properly reclaimed. This call should be at the end of the actor's function, not in a on_exit callback. +.. _s4u_raii: + Memory Management ***************** @@ -369,108 +375,634 @@ shouldn't), using :cpp:func:`simgrid::s4u::Host::destroy`. .. include:: ../../examples/README.rst -C++ API Reference -***************** +API Reference +************* + +.. _API_s4u_simulation_object: + +================== +Simulation objects +================== + +.. _API_s4u_Actor: + +============== +⁣  class Actor +============== + +.. autodoxyclass:: simgrid::s4u::Actor + +.. doxygentypedef:: ActorPtr + +.. doxygentypedef:: aid_t + +Creating actors +--------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code:: C++ + + #include + + .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, const std::function< void()> &code) + .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, F code) + .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, F code, Args... args) + .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, const std::string &function, std::vector< std::string > args) + + .. autodoxymethod:: simgrid::s4u::Actor::init(const std::string &name, s4u::Host *host) + .. autodoxymethod:: simgrid::s4u::Actor::start(const std::function< void()> &code) + + .. group-tab:: Python + + .. code:: Python + + from simgrid import Actor + + .. automethod:: simgrid.Actor.create + + .. group-tab:: C + + .. code:: C + + #include + + .. doxygentypedef:: sg_actor_t + .. cpp:type:: const s4u_Actor* const_sg_actor_t + + Pointer to a constant actor object. + + .. autodoxymethod:: sg_actor_init(const char *name, sg_host_t host) + .. autodoxymethod:: sg_actor_start(sg_actor_t actor, xbt_main_func_t code, int argc, char **argv) + + .. autodoxymethod:: sg_actor_attach(const char *name, void *data, sg_host_t host, xbt_dict_t properties) + .. autodoxymethod:: sg_actor_detach() + + .. autodoxymethod:: sg_actor_ref(const_sg_actor_t actor) + .. autodoxymethod:: sg_actor_unref(const_sg_actor_t actor) + +Searching specific actors +------------------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Actor::by_pid(aid_t pid) + .. autodoxymethod:: simgrid::s4u::Actor::self() + + .. group-tab:: Python + + .. automethod:: simgrid.Actor.by_pid + .. automethod:: simgrid.Actor.self + + .. group-tab:: C + + .. autodoxymethod:: sg_actor_by_PID(aid_t pid) + .. autodoxymethod:: sg_actor_self() + +Querying info about actors +-------------------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Actor::get_cname + .. autodoxymethod:: simgrid::s4u::Actor::get_name + .. autodoxymethod:: simgrid::s4u::Actor::get_pid + .. autodoxymethod:: simgrid::s4u::Actor::get_ppid + .. autodoxymethod:: simgrid::s4u::Actor::get_properties() const + .. autodoxymethod:: simgrid::s4u::Actor::get_property(const std::string &key) const + .. autodoxymethod:: simgrid::s4u::Actor::set_property(const std::string &key, const std::string &value) + + .. autodoxymethod:: simgrid::s4u::Actor::get_host + .. autodoxymethod:: simgrid::s4u::Actor::set_host + + .. autodoxymethod:: simgrid::s4u::Actor::get_refcount() + .. autodoxymethod:: simgrid::s4u::Actor::get_impl + + .. group-tab:: Python + + .. autoattribute:: simgrid.Actor.name + .. autoattribute:: simgrid.Actor.host + .. autoattribute:: simgrid.Actor.pid + .. autoattribute:: simgrid.Actor.ppid + + .. group-tab:: C + + .. autodoxymethod:: sg_actor_get_name(const_sg_actor_t actor) + .. autodoxymethod:: sg_actor_get_PID(const_sg_actor_t actor) + .. autodoxymethod:: sg_actor_get_PPID(const_sg_actor_t actor) + .. autodoxymethod:: sg_actor_get_properties(const_sg_actor_t actor) + .. autodoxymethod:: sg_actor_get_property_value(const_sg_actor_t actor, const char *name) + + .. autodoxymethod:: sg_actor_get_host(const_sg_actor_t actor) + .. autodoxymethod:: sg_actor_set_host(sg_actor_t actor, sg_host_t host) + + .. autodoxymethod:: sg_actor_data(const_sg_actor_t actor) + .. autodoxymethod:: sg_actor_data_set(sg_actor_t actor, void *userdata) + +Suspending and resuming actors +------------------------------ + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Actor::suspend() + .. autodoxymethod:: simgrid::s4u::Actor::resume() + .. autodoxymethod:: simgrid::s4u::Actor::is_suspended() + + .. group-tab:: Python + + .. automethod:: simgrid.Actor.resume + .. automethod:: simgrid.Actor.suspend + .. automethod:: simgrid.Actor.is_suspended + + .. group-tab:: C + + .. autodoxymethod:: sg_actor_suspend(sg_actor_t actor) + .. autodoxymethod:: sg_actor_resume(sg_actor_t actor) + .. autodoxymethod:: sg_actor_is_suspended(sg_actor_t actor) + +Specifying when actors should terminate +--------------------------------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Actor::kill() + .. autodoxymethod:: simgrid::s4u::Actor::kill_all() + .. autodoxymethod:: simgrid::s4u::Actor::set_kill_time(double time) + .. autodoxymethod:: simgrid::s4u::Actor::get_kill_time() + + .. autodoxymethod:: simgrid::s4u::Actor::restart() + .. autodoxymethod:: simgrid::s4u::Actor::daemonize() + .. autodoxymethod:: simgrid::s4u::Actor::is_daemon + + .. group-tab:: Python + + .. automethod:: simgrid.Actor.kill + .. automethod:: simgrid.Actor.kill_all + + .. automethod:: simgrid.Actor.daemonize + .. automethod:: simgrid.Actor.is_daemon + + .. group-tab:: C + + .. autodoxymethod:: sg_actor_kill(sg_actor_t actor) + .. autodoxymethod:: sg_actor_kill_all() + .. autodoxymethod:: sg_actor_set_kill_time(sg_actor_t actor, double kill_time) + + .. autodoxymethod:: sg_actor_restart(sg_actor_t actor) + .. autodoxymethod:: sg_actor_daemonize(sg_actor_t actor) + +.. _API_s4u_Actor_end: + +Reacting to the end of actors +----------------------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Actor::on_exit + .. autodoxymethod:: simgrid::s4u::Actor::join() + .. autodoxymethod:: simgrid::s4u::Actor::join(double timeout) + .. autodoxymethod:: simgrid::s4u::Actor::set_auto_restart(bool autorestart) + + .. group-tab:: Python + + .. automethod:: simgrid.Actor.join + + .. group-tab:: C + + .. autodoxymethod:: sg_actor_join(sg_actor_t actor, double timeout) + .. autodoxymethod:: sg_actor_set_auto_restart(sg_actor_t actor, int auto_restart) + +Signals +------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxyvar:: simgrid::s4u::Actor::on_creation + .. autodoxyvar:: simgrid::s4u::Actor::on_suspend + .. autodoxyvar:: simgrid::s4u::Actor::on_resume + .. autodoxyvar:: simgrid::s4u::Actor::on_sleep + .. autodoxyvar:: simgrid::s4u::Actor::on_wake_up + .. autodoxyvar:: simgrid::s4u::Actor::on_termination + .. autodoxyvar:: simgrid::s4u::Actor::on_destruction .. _API_s4u_this_actor: -========================= -namespace s4u::this_actor -========================= +==================== +⁣  The current actor +==================== -.. doxygennamespace:: simgrid::s4u::this_actor -.. _API_s4u_Activity: +These functions can be used in your user code to interact with the actor +currently running (the one retrieved with :cpp:func:`simgrid::s4u::Actor::self`). +Using these functions can greatly improve the code readability. -============= -s4u::Activity -============= +Querying info +------------- -.. doxygenclass:: simgrid::s4u::Activity - :members: - :protected-members: - :undoc-members: +.. tabs:: -.. _API_s4u_Actor: + .. group-tab:: C++ -========== -s4u::Actor -========== + .. autodoxymethod:: simgrid::s4u::this_actor::get_cname() + .. autodoxymethod:: simgrid::s4u::this_actor::get_name() + .. autodoxymethod:: simgrid::s4u::this_actor::get_pid() + .. autodoxymethod:: simgrid::s4u::this_actor::get_ppid() + .. autodoxymethod:: simgrid::s4u::this_actor::is_maestro() -.. doxygentypedef:: ActorPtr + .. autodoxymethod:: simgrid::s4u::this_actor::get_host() + .. autodoxymethod:: simgrid::s4u::this_actor::set_host(Host *new_host) -.. doxygentypedef:: aid_t + .. group-tab:: Python + + .. autofunction:: simgrid.this_actor.get_host + .. autofunction:: simgrid.this_actor.set_host + + .. group-tab:: C + + .. autodoxymethod:: sg_actor_self_data() + .. autodoxymethod:: sg_actor_self_data_set(void *data) + .. autodoxymethod:: sg_actor_self_get_name() + .. autodoxymethod:: sg_actor_self_get_pid() + .. autodoxymethod:: sg_actor_self_get_ppid() + .. autodoxymethod:: sg_host_self() + .. autodoxymethod:: sg_host_self_get_name() + +Suspending and resuming +----------------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::this_actor::suspend() + .. autodoxymethod:: simgrid::s4u::this_actor::yield() + + .. group-tab:: Python + + .. autofunction:: simgrid.this_actor.suspend + .. autofunction:: simgrid.this_actor.yield_ + +Logging messages +---------------- + +.. tabs:: + + .. group-tab:: Python + + .. autofunction:: simgrid.this_actor.info + .. autofunction:: simgrid.this_actor.error + +Sleeping +-------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::this_actor::sleep_for(double duration) + .. autodoxymethod:: simgrid::s4u::this_actor::sleep_for(std::chrono::duration< Rep, Period > duration) + .. autodoxymethod:: simgrid::s4u::this_actor::sleep_until(const SimulationTimePoint< Duration > &wakeup_time) + .. autodoxymethod:: simgrid::s4u::this_actor::sleep_until(double wakeup_time) + + .. group-tab:: Python + + .. autofunction:: simgrid.this_actor.sleep_for + .. autofunction:: simgrid.this_actor.sleep_until + + .. group-tab:: C + + .. autodoxymethod:: sg_actor_sleep_for(double duration) + +Simulating executions +--------------------- + +Simulate the execution of some code on this actor. You can either simulate +parallel or sequential code, and you can either block upon the termination of +the execution, or start an asynchronous activity. + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::this_actor::exec_async(double flops_amounts) + .. autodoxymethod:: simgrid::s4u::this_actor::exec_init(const std::vector< s4u::Host * > &hosts, const std::vector< double > &flops_amounts, const std::vector< double > &bytes_amounts) + .. autodoxymethod:: simgrid::s4u::this_actor::exec_init(double flops_amounts) + .. autodoxymethod:: simgrid::s4u::this_actor::execute(double flop) + .. autodoxymethod:: simgrid::s4u::this_actor::execute(double flop, double priority) + .. autodoxymethod:: simgrid::s4u::this_actor::parallel_execute(const std::vector< s4u::Host * > &hosts, const std::vector< double > &flops_amounts, const std::vector< double > &bytes_amounts) + .. autodoxymethod:: simgrid::s4u::this_actor::parallel_execute(const std::vector< s4u::Host * > &hosts, const std::vector< double > &flops_amounts, const std::vector< double > &bytes_amounts, double timeout) + + .. group-tab:: Python + + .. autofunction:: simgrid.this_actor.exec_init + .. autofunction:: simgrid.this_actor.execute + + .. group-tab:: C + + .. autodoxymethod:: sg_actor_self_execute(double flops) + +Exiting +------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::this_actor::exit() + .. autodoxymethod:: simgrid::s4u::this_actor::on_exit(const std::function< void(bool)> &fun) + + .. group-tab:: Python + + .. autofunction:: simgrid.this_actor.exit + .. autofunction:: simgrid.this_actor.on_exit + +.. _API_s4u_Engine: + +==================== +⁣  Simulation Engine +==================== + +.. autodoxyclass:: simgrid::s4u::Engine + +Initialization +-------------- + +.. tabs:: -.. doxygenclass:: simgrid::s4u::Actor + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Engine::Engine(int *argc, char **argv) + .. autodoxymethod:: simgrid::s4u::Engine::is_initialized() + .. autodoxymethod:: simgrid::s4u::Engine::shutdown() + .. autodoxymethod:: simgrid::s4u::Engine::set_config(const std::string &str) + + .. autodoxymethod:: simgrid::s4u::Engine::load_deployment(const std::string &deploy) + .. autodoxymethod:: simgrid::s4u::Engine::load_platform(const std::string &platf) + .. autodoxymethod:: simgrid::s4u::Engine::register_actor(const std::string &name) + .. autodoxymethod:: simgrid::s4u::Engine::register_actor(const std::string &name, F code) + .. autodoxymethod:: simgrid::s4u::Engine::register_default(int(*code)(int, char **)) + .. autodoxymethod:: simgrid::s4u::Engine::register_function(const std::string &name, int(*code)(int, char **)) + .. autodoxymethod:: simgrid::s4u::Engine::register_function(const std::string &name, void(*code)(std::vector< std::string >)) + + .. group-tab:: Python + + .. automethod:: simgrid.Engine.load_deployment + .. automethod:: simgrid.Engine.load_platform + .. automethod:: simgrid.Engine.register_actor + + .. group-tab:: C + + .. autodoxymethod:: simgrid_init + + .. autodoxymethod:: simgrid_load_deployment + .. autodoxymethod:: simgrid_load_platform + .. autodoxymethod:: simgrid_register_default + .. autodoxymethod:: simgrid_register_function + +Run the simulation +------------------ + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Engine::get_clock() + .. autodoxymethod:: simgrid::s4u::Engine::run() + + .. group-tab:: Python + + .. automethod:: simgrid.Engine.get_clock + .. automethod:: simgrid.Engine.run + + .. group-tab:: C + + .. autodoxymethod:: simgrid_get_clock + .. autodoxymethod:: simgrid_run + +Retrieving actors +----------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Engine::get_actor_count() + .. autodoxymethod:: simgrid::s4u::Engine::get_all_actors() + .. autodoxymethod:: simgrid::s4u::Engine::get_filtered_actors(const std::function< bool(ActorPtr)> &filter) + + .. group-tab:: C + + .. autodoxymethod:: simgrid_get_actor_count() + +Retrieving hosts +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Engine::get_all_hosts() + .. autodoxymethod:: simgrid::s4u::Engine::get_host_count() + .. autodoxymethod:: simgrid::s4u::Engine::get_filtered_hosts(const std::function< bool(Host *)> &filter) + .. autodoxymethod:: simgrid::s4u::Engine::host_by_name(const std::string &name) + .. autodoxymethod:: simgrid::s4u::Engine::host_by_name_or_null(const std::string &name) + + .. group-tab:: Python + + .. automethod:: simgrid.Engine.get_all_hosts + +Retrieving links +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Engine::get_all_links() + .. autodoxymethod:: simgrid::s4u::Engine::get_link_count() + .. autodoxymethod:: simgrid::s4u::Engine::get_filtered_links + .. autodoxymethod:: simgrid::s4u::Engine::link_by_name(const std::string &name) + .. autodoxymethod:: simgrid::s4u::Engine::link_by_name_or_null(const std::string &name) + +Interacting with the routing +---------------------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Engine::get_all_netpoints() + .. autodoxymethod:: simgrid::s4u::Engine::get_filtered_netzones() + .. autodoxymethod:: simgrid::s4u::Engine::get_instance() + .. autodoxymethod:: simgrid::s4u::Engine::get_netzone_root() + .. autodoxymethod:: simgrid::s4u::Engine::netpoint_by_name_or_null(const std::string &name) + .. autodoxymethod:: simgrid::s4u::Engine::netzone_by_name_or_null(const std::string &name) + .. autodoxymethod:: simgrid::s4u::Engine::set_netzone_root(const NetZone *netzone) + +Signals +------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxyvar:: simgrid::s4u::Engine::on_deadlock + .. autodoxyvar:: simgrid::s4u::Engine::on_platform_created + .. autodoxyvar:: simgrid::s4u::Engine::on_platform_creation + .. autodoxyvar:: simgrid::s4u::Engine::on_simulation_end + .. autodoxyvar:: simgrid::s4u::Engine::on_time_advance + +.. _API_s4u_Mailbox: + +================ +⁣  class Mailbox +================ + +Please also refer to the :ref:`full doc on s4u::Mailbox `. + +.. doxygenclass:: simgrid::s4u::Mailbox :members: :protected-members: :undoc-members: +.. _API_s4u_Resource: -.. _API_s4u_Barrier: +========= +Resources +========= -============ -s4u::Barrier -============ +.. _API_s4u_Disk: -.. doxygentypedef:: BarrierPtr +============= +⁣  class Disk +============= -.. doxygenclass:: simgrid::s4u::Barrier +.. doxygenclass:: simgrid::s4u::Disk :members: :protected-members: :undoc-members: -.. _API_s4u_Comm: -========= -s4u::Comm -========= -.. doxygentypedef:: CommPtr +.. _API_s4u_Host: -.. doxygenclass:: simgrid::s4u::Comm +============= +⁣  class Host +============= + +.. doxygenclass:: simgrid::s4u::Host :members: :protected-members: :undoc-members: -.. _API_s4u_ConditionVariable: +.. _API_s4u_Link: -====================== -s4u::ConditionVariable -====================== +============= +⁣  class Link +============= -.. doxygentypedef:: ConditionVariablePtr +.. doxygenclass:: simgrid::s4u::Link + :members: + :protected-members: + :undoc-members: -.. doxygenclass:: simgrid::s4u::ConditionVariable +.. _API_s4u_NetZone: + +================ +⁣  class NetZone +================ + +.. doxygenclass:: simgrid::s4u::NetZone :members: :protected-members: :undoc-members: -.. _API_s4u_Disk: +.. _API_s4u_VirtualMachine: -============ -s4u::Disk -============ +======================= +⁣  class VirtualMachine +======================= -.. doxygenclass:: simgrid::s4u::Disk +.. doxygenclass:: simgrid::s4u::VirtualMachine :members: :protected-members: :undoc-members: -.. _API_s4u_Engine: +.. autodoxymethod:: sg_vm_create_core +.. autodoxymethod:: sg_vm_create_multicore +.. autodoxymethod:: sg_vm_get_name +.. autodoxymethod:: sg_vm_get_pm +.. autodoxymethod:: sg_vm_is_created +.. autodoxymethod:: sg_vm_is_running +.. autodoxymethod:: sg_vm_is_suspended +.. autodoxymethod:: sg_vm_start +.. autodoxymethod:: sg_vm_suspend +.. autodoxymethod:: sg_vm_resume +.. autodoxymethod:: sg_vm_shutdown +.. autodoxymethod:: sg_vm_destroy -=========== -s4u::Engine -=========== +.. _API_s4u_Activity: + +============== +class Activity +============== + +.. autodoxyclass:: simgrid::s4u::Activity + + **Known subclasses:** + :ref:`Communications ` (started on Mailboxes and consuming links), + :ref:`Executions ` (started on Host and consuming CPU resources) + :ref:`I/O ` (started on and consumming disks). + See also the :ref:`section on activities ` above. -.. doxygenclass:: simgrid::s4u::Engine +Querying info about activities +------------------------------ + + .. autodoxymethod:: simgrid::s4u::Activity::get_remaining() + .. autodoxymethod:: simgrid::s4u::Activity::get_state() + .. autodoxymethod:: simgrid::s4u::Activity::set_remaining(double remains) + .. autodoxymethod:: simgrid::s4u::Activity::get_impl + +Activities lifecycle +-------------------- + + .. autodoxymethod:: simgrid::s4u::Activity::start + .. autodoxymethod:: simgrid::s4u::Activity::cancel + .. autodoxymethod:: simgrid::s4u::Activity::test + .. autodoxymethod:: simgrid::s4u::Activity::wait + .. autodoxymethod:: simgrid::s4u::Activity::wait_for + .. autodoxymethod:: simgrid::s4u::Activity::wait_until(double time_limit) + +.. _API_s4u_Comm: + +============= +⁣  class Comm +============= + +.. doxygentypedef:: CommPtr + +.. doxygenclass:: simgrid::s4u::Comm :members: :protected-members: :undoc-members: .. _API_s4u_Exec: -========= -s4u::Exec -========= +============= +⁣  class Exec +============= .. doxygentypedef:: ExecPtr @@ -481,9 +1013,9 @@ s4u::Exec .. _API_s4u_ExecSeq: -============ -s4u::ExecSeq -============ +================== +⁣    class ExecSeq +================== .. doxygentypedef:: ExecSeqPtr @@ -494,9 +1026,9 @@ s4u::ExecSeq .. _API_s4u_ExecPar: -============ -s4u::ExecPar -============ +================== +⁣    class ExecPar +================== .. doxygentypedef:: ExecParPtr @@ -505,22 +1037,11 @@ s4u::ExecPar :protected-members: :undoc-members: -.. _API_s4u_Host: - -========= -s4u::Host -========= - -.. doxygenclass:: simgrid::s4u::Host - :members: - :protected-members: - :undoc-members: - .. _API_s4u_Io: -======= -s4u::Io -======= +=========== +⁣  class Io +=========== .. doxygentypedef:: IoPtr @@ -529,104 +1050,226 @@ s4u::Io :protected-members: :undoc-members: -.. _API_s4u_Link: +.. _API_s4u_Synchronizations: -========= -s4u::Link -========= +======================= +Synchronization Objects +======================= -.. doxygenclass:: simgrid::s4u::Link - :members: - :protected-members: - :undoc-members: +.. _API_s4u_Mutex: -.. _API_s4u_Mailbox: +============== +⁣  Mutex +============== -============ -s4u::Mailbox -============ +.. autodoxyclass:: simgrid::s4u::Mutex -Please also refer to the :ref:`full doc on s4u::Mailbox `. +Basic management +---------------- -.. doxygenclass:: simgrid::s4u::Mailbox - :members: - :protected-members: - :undoc-members: + .. tabs:: -.. _API_s4u_Mutex: + .. group-tab:: C++ -========== -s4u::Mutex -========== + .. code-block:: C++ -.. doxygentypedef:: MutexPtr + #include -.. doxygenclass:: simgrid::s4u::Mutex - :members: - :protected-members: - :undoc-members: + .. doxygentypedef:: MutexPtr -.. _API_s4u_NetZone: + .. autodoxymethod:: simgrid::s4u::Mutex::Mutex(kernel::activity::MutexImpl *mutex) + .. autodoxymethod:: simgrid::s4u::Mutex::create() + .. autodoxymethod:: simgrid::s4u::Mutex::~Mutex() -============ -s4u::NetZone -============ + .. group-tab:: C -.. doxygenclass:: simgrid::s4u::NetZone - :members: - :protected-members: - :undoc-members: + .. code-block:: C -.. _API_s4u_Semaphore: + #include -============== -s4u::Semaphore -============== + .. doxygentypedef:: sg_mutex_t + .. cpp:type:: const s4u_Mutex* const_sg_mutex_t -.. doxygentypedef:: SemaphorePtr + Pointer to a constant mutex object. -.. doxygenclass:: simgrid::s4u::Semaphore - :members: - :protected-members: - :undoc-members: + .. autodoxymethod:: sg_mutex_init() + .. autodoxymethod:: sg_mutex_destroy(const_sg_mutex_t mutex) -.. _API_s4u_VirtualMachine: +Locking +------- -=================== -s4u::VirtualMachine -=================== + .. tabs:: -.. doxygenclass:: simgrid::s4u::VirtualMachine - :members: - :protected-members: - :undoc-members: + .. group-tab:: C++ -C API Reference -*************** + .. autodoxymethod:: simgrid::s4u::Mutex::lock() + .. autodoxymethod:: simgrid::s4u::Mutex::try_lock() + .. autodoxymethod:: simgrid::s4u::Mutex::unlock() -============== -Main functions -============== + .. group-tab:: C + + .. autodoxymethod:: sg_mutex_lock(sg_mutex_t mutex) + .. autodoxymethod:: sg_mutex_try_lock(sg_mutex_t mutex) + .. autodoxymethod:: sg_mutex_unlock(sg_mutex_t mutex) + +.. _API_s4u_Barrier: + +================ +⁣  Barrier +================ + +.. autodoxyclass:: simgrid::s4u::Barrier + + .. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + .. doxygentypedef:: BarrierPtr + + .. autodoxymethod:: simgrid::s4u::Barrier::Barrier(unsigned int expected_actors) + .. autodoxymethod:: simgrid::s4u::Barrier::create(unsigned int expected_actors) + .. autodoxymethod:: simgrid::s4u::Barrier::wait() + + .. group-tab:: C + + .. code-block:: C + + #include + + .. doxygentypedef:: sg_bar_t + .. cpp:type:: const s4u_Barrier* const_sg_bar_t + + Pointer to a constant barrier object. + + .. autodoxymethod:: sg_barrier_init(unsigned int count) + .. autodoxymethod:: sg_barrier_destroy(const_sg_bar_t bar) + .. autodoxymethod:: sg_barrier_wait(sg_bar_t bar) + + +.. _API_s4u_ConditionVariable: + +========================== +⁣  Condition variable +========================== + +.. autodoxyclass:: simgrid::s4u::ConditionVariable -.. doxygenfunction:: simgrid_init -.. doxygenfunction:: simgrid_get_clock -.. doxygenfunction:: simgrid_load_deployment -.. doxygenfunction:: simgrid_load_platform -.. doxygenfunction:: simgrid_register_default -.. doxygenfunction:: simgrid_register_function -.. doxygenfunction:: simgrid_run +Basic management +---------------- + + .. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + .. doxygentypedef:: ConditionVariablePtr + + .. autodoxymethod:: simgrid::s4u::ConditionVariable::create() + + .. group-tab:: C + + .. code-block:: C + + #include + + .. doxygentypedef:: sg_cond_t + .. doxygenfunction:: sg_cond_init + .. doxygenfunction:: sg_cond_destroy + +Waiting and notifying +--------------------- + + .. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::ConditionVariable::notify_all() + .. autodoxymethod:: simgrid::s4u::ConditionVariable::notify_one() + .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait(s4u::MutexPtr lock) + .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait(const std::unique_lock< s4u::Mutex > &lock) + .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait(const std::unique_lock< Mutex > &lock, P pred) + .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, double duration) + .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, double duration, P pred) + .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, std::chrono::duration< Rep, Period > duration) + .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, std::chrono::duration< Rep, Period > duration, P pred) + .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, const SimulationTimePoint< Duration > &timeout_time) + .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, const SimulationTimePoint< Duration > &timeout_time, P pred) + .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, double timeout_time) + .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, double timeout_time, P pred) + + .. group-tab:: C + + .. doxygenfunction:: sg_cond_notify_all + .. doxygenfunction:: sg_cond_notify_one + .. doxygenfunction:: sg_cond_wait + .. doxygenfunction:: sg_cond_wait_for + +.. _API_s4u_Semaphore: ================== -Condition Variable +⁣  Semaphore ================== -See also the :ref:`C++ API `. +.. autodoxyclass:: simgrid::s4u::Semaphore + + +Basic management +---------------- + + .. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ -.. doxygenfunction:: sg_cond_init -.. doxygenfunction:: sg_cond_notify_all -.. doxygenfunction:: sg_cond_notify_one -.. doxygenfunction:: sg_cond_wait -.. doxygenfunction:: sg_cond_wait_for + #include + + .. doxygentypedef:: SemaphorePtr + .. autodoxymethod:: simgrid::s4u::Semaphore::Semaphore(unsigned int initial_capacity) + .. autodoxymethod:: simgrid::s4u::Semaphore::~Semaphore() + .. autodoxymethod:: simgrid::s4u::Semaphore::create(unsigned int initial_capacity) + + .. group-tab:: C + + .. code-block:: C + + #include + + .. doxygentypedef:: sg_sem_t + .. cpp:type:: const s4u_Semaphore* const_sg_sem_t + + Pointer to a constant semaphore object. + + .. autodoxymethod:: sg_sem_init(int initial_value) + .. autodoxymethod:: sg_sem_destroy(const_sg_sem_t sem) + +Locking +------- + + .. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Semaphore::acquire() + .. autodoxymethod:: simgrid::s4u::Semaphore::acquire_timeout(double timeout) + .. autodoxymethod:: simgrid::s4u::Semaphore::get_capacity() + .. autodoxymethod:: simgrid::s4u::Semaphore::release() + .. autodoxymethod:: simgrid::s4u::Semaphore::would_block() + + .. group-tab:: C + + .. autodoxymethod:: sg_sem_acquire(sg_sem_t sem) + .. autodoxymethod:: sg_sem_acquire_timeout(sg_sem_t sem, double timeout) + .. autodoxymethod:: sg_sem_get_capacity(sg_sem_t sem) + .. autodoxymethod:: sg_sem_release(sg_sem_t sem) + .. autodoxymethod:: sg_sem_would_block(sg_sem_t sem) Python API Reference ******************** @@ -641,13 +1284,6 @@ this_actor .. automodule:: simgrid.this_actor :members: -=========== -Class Actor -=========== - -.. autoclass:: simgrid.Actor - :members: - ========== Class Comm ========== @@ -655,13 +1291,6 @@ Class Comm .. autoclass:: simgrid.Comm :members: -============ -Class Engine -============ - -.. autoclass:: simgrid.Engine - :members: - ========== Class Exec ========== @@ -682,3 +1311,7 @@ Class Mailbox .. autoclass:: simgrid.Mailbox :members: + +.. |hr| raw:: html + +