X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/a4a6081750de4dea9877433891f32109eeabbcd0..471d0736505fc6cfd8f018bdeb8bd3846ee2adad:/docs/source/app_s4u.rst diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index fac7ad0724..8123177b29 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -392,12 +392,10 @@ Simulation objects .. autodoxyclass:: simgrid::s4u::Actor -.. doxygentypedef:: ActorPtr - .. doxygentypedef:: aid_t -Creating actors ---------------- +Basic management +---------------- .. tabs:: @@ -405,7 +403,36 @@ Creating actors .. code:: C++ - #include + #include + + .. doxygentypedef:: ActorPtr + + .. group-tab:: Python + + .. code:: Python + + from simgrid import Actor + + .. 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_ref(const_sg_actor_t actor) + .. autodoxymethod:: sg_actor_unref(const_sg_actor_t actor) + +Creating actors +--------------- + +.. tabs:: + + .. group-tab:: C++ .. 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) @@ -417,29 +444,18 @@ Creating actors .. group-tab:: Python - .. code:: Python - - from simgrid import Actor - .. automethod:: simgrid.Actor.create .. group-tab:: C - .. code:: C - - #include - .. 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 -------------------------- +Retrieving actors +----------------- .. tabs:: @@ -458,8 +474,8 @@ Searching specific actors .. autodoxymethod:: sg_actor_by_PID(aid_t pid) .. autodoxymethod:: sg_actor_self() -Querying info about actors --------------------------- +Querying info +------------- .. tabs:: @@ -600,9 +616,129 @@ Signals ⁣  The current actor ==================== -Static methods working on the current actor (see :ref:`API_s4u_Actor`). +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. + +Querying info +------------- + +.. tabs:: + + .. group-tab:: C++ + + .. 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() + + .. autodoxymethod:: simgrid::s4u::this_actor::get_host() + .. autodoxymethod:: simgrid::s4u::this_actor::set_host(Host *new_host) + + .. 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++ -.. doxygennamespace:: simgrid::s4u::this_actor + .. 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: @@ -699,6 +835,10 @@ Retrieving hosts .. automethod:: simgrid.Engine.get_all_hosts + .. group-tab:: C + + See also :cpp:func:`sg_host_list` and :cpp:func:`sg_host_count`. + Retrieving links ---------------- @@ -746,191 +886,930 @@ Signals ⁣  class Mailbox ================ +.. autodoxyclass:: simgrid::s4u::Mailbox + Please also refer to the :ref:`full doc on s4u::Mailbox `. -.. doxygenclass:: simgrid::s4u::Mailbox - :members: - :protected-members: - :undoc-members: -.. _API_s4u_Resource: +Basic management +---------------- -========= -Resources -========= +.. tabs:: -.. _API_s4u_Disk: + .. group-tab:: C++ -============= -⁣  class Disk -============= + .. code-block:: C++ -.. doxygenclass:: simgrid::s4u::Disk - :members: - :protected-members: - :undoc-members: + #include + Note that there is no MailboxPtr type, and that you cannot use the RAII + idiom on mailboxes because they are internal objects to the simulation + engine. Once created, there is no way to destroy a mailbox before the end + of the simulation. + + .. autodoxymethod:: simgrid::s4u::Mailbox::by_name(const std::string &name) + .. group-tab:: Python -.. _API_s4u_Host: + .. automethod:: simgrid.Mailbox.by_name -============= -⁣  class Host -============= +Querying info +------------- -.. doxygenclass:: simgrid::s4u::Host - :members: - :protected-members: - :undoc-members: +.. tabs:: -.. _API_s4u_Link: + .. group-tab:: C++ -============= -⁣  class Link -============= + .. autodoxymethod:: simgrid::s4u::Mailbox::get_cname() + .. autodoxymethod:: simgrid::s4u::Mailbox::get_name() -.. doxygenclass:: simgrid::s4u::Link - :members: - :protected-members: - :undoc-members: + .. group-tab:: Python -.. _API_s4u_NetZone: + .. autoattribute:: simgrid.Mailbox.name -================ -⁣  class NetZone -================ +Sending data +------------ -.. doxygenclass:: simgrid::s4u::NetZone - :members: - :protected-members: - :undoc-members: +.. tabs:: -.. _API_s4u_VirtualMachine: + .. group-tab:: C++ -======================= -⁣  class VirtualMachine -======================= + .. autodoxymethod:: simgrid::s4u::Mailbox::put(void *payload, uint64_t simulated_size_in_bytes) + .. autodoxymethod:: simgrid::s4u::Mailbox::put(void *payload, uint64_t simulated_size_in_bytes, double timeout) + .. autodoxymethod:: simgrid::s4u::Mailbox::put_async(void *data, uint64_t simulated_size_in_bytes) + .. autodoxymethod:: simgrid::s4u::Mailbox::put_init() + .. autodoxymethod:: simgrid::s4u::Mailbox::put_init(void *data, uint64_t simulated_size_in_bytes) -.. doxygenclass:: simgrid::s4u::VirtualMachine - :members: - :protected-members: - :undoc-members: + .. group-tab:: Python -.. 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 + .. automethod:: simgrid.Mailbox.put + .. automethod:: simgrid.Mailbox.put_async -.. _API_s4u_Activity: -============== -class Activity -============== +Receiving data +-------------- -.. autodoxyclass:: simgrid::s4u::Activity +.. tabs:: - **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. + .. group-tab:: C++ -Querying info about activities ------------------------------- + .. autodoxymethod:: simgrid::s4u::Mailbox::empty() + .. autodoxymethod:: simgrid::s4u::Mailbox::front() + .. autodoxymethod:: simgrid::s4u::Mailbox::get() + .. autodoxymethod:: simgrid::s4u::Mailbox::get(double timeout) + .. autodoxymethod:: simgrid::s4u::Mailbox::get_async(void **data) + .. autodoxymethod:: simgrid::s4u::Mailbox::get_init() + .. autodoxymethod:: simgrid::s4u::Mailbox::iprobe(int type, bool(*match_fun)(void *, void *, kernel::activity::CommImpl *), void *data) + .. autodoxymethod:: simgrid::s4u::Mailbox::listen() + .. autodoxymethod:: simgrid::s4u::Mailbox::ready() - .. 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 + .. group-tab:: Python -Activities lifecycle --------------------- + .. automethod:: simgrid.Mailbox.get - .. 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) + .. group-tab:: C -.. _API_s4u_Comm: + .. autodoxymethod:: sg_mailbox_listen(const char *alias) -============= -⁣  class Comm -============= +Receiving actor +--------------- -.. doxygentypedef:: CommPtr +See :ref:`s4u_receiving_actor`. -.. doxygenclass:: simgrid::s4u::Comm - :members: - :protected-members: - :undoc-members: +.. tabs:: -.. _API_s4u_Exec: + .. group-tab:: C++ -============= -⁣  class Exec -============= + .. autodoxymethod:: simgrid::s4u::Mailbox::get_receiver() + .. autodoxymethod:: simgrid::s4u::Mailbox::set_receiver(ActorPtr actor) -.. doxygentypedef:: ExecPtr + .. group-tab:: C -.. doxygenclass:: simgrid::s4u::Exec - :members: - :protected-members: - :undoc-members: + .. autodoxymethod:: ::sg_mailbox_set_receiver(const char *alias) + +.. _API_s4u_Resource: -.. _API_s4u_ExecSeq: +========= +Resources +========= -================== -⁣    class ExecSeq -================== +.. _API_s4u_Disk: -.. doxygentypedef:: ExecSeqPtr +============= +⁣  class Disk +============= -.. doxygenclass:: simgrid::s4u::ExecSeq - :members: - :protected-members: - :undoc-members: +.. autodoxyclass:: simgrid::s4u::Disk -.. _API_s4u_ExecPar: +Basic management +---------------- -================== -⁣    class ExecPar -================== +.. tabs:: -.. doxygentypedef:: ExecParPtr + .. group-tab:: C++ -.. doxygenclass:: simgrid::s4u::ExecPar - :members: - :protected-members: - :undoc-members: + .. code-block:: C++ -.. _API_s4u_Io: + #include -=========== -⁣  class Io -=========== + Note that there is no DiskPtr type, and that you cannot use the RAII + idiom on disks because SimGrid does not allow (yet) to create nor + destroy resources once the simulation is started. + -.. doxygentypedef:: IoPtr +Querying info +------------- -.. doxygenclass:: simgrid::s4u::Io - :members: - :protected-members: - :undoc-members: +.. tabs:: -.. _API_s4u_Synchronizations: + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Disk::get_cname() + .. autodoxymethod:: simgrid::s4u::Disk::get_host() + .. autodoxymethod:: simgrid::s4u::Disk::get_name() + .. autodoxymethod:: simgrid::s4u::Disk::get_properties() + .. autodoxymethod:: simgrid::s4u::Disk::get_property(const std::string &key) + .. autodoxymethod:: simgrid::s4u::Disk::get_read_bandwidth() + .. autodoxymethod:: simgrid::s4u::Disk::get_write_bandwidth() + .. autodoxymethod:: simgrid::s4u::Disk::set_property(const std::string &, const std::string &value) + +I/O operations +-------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Disk::io_init(sg_size_t size, s4u::Io::OpType type) + .. autodoxymethod:: simgrid::s4u::Disk::read(sg_size_t size) + .. autodoxymethod:: simgrid::s4u::Disk::read_async(sg_size_t size) + .. autodoxymethod:: simgrid::s4u::Disk::write(sg_size_t size) + .. autodoxymethod:: simgrid::s4u::Disk::write_async(sg_size_t size) + +Signals +------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxyvar:: simgrid::s4u::Disk::on_creation + .. autodoxyvar:: simgrid::s4u::Disk::on_destruction + .. autodoxyvar:: simgrid::s4u::Disk::on_state_change + + +.. _API_s4u_Host: + +============= +⁣  class Host +============= + +.. autodoxyclass:: simgrid::s4u::Host + +Basic management +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + Note that there is no HostPtr type, and that you cannot use the RAII + idiom on hosts because SimGrid does not allow (yet) to create nor + destroy resources once the simulation is started. + + .. autodoxymethod:: simgrid::s4u::Host::destroy() + + .. group-tab:: Python + + .. code:: Python + + from simgrid import Host + + .. group-tab:: C + + .. code:: C + + #include + + .. doxygentypedef:: sg_host_t + .. cpp:type:: const s4u_Host* const_sg_host_t + + Pointer to a constant host object. + +Retrieving hosts +---------------- + +.. tabs:: + + .. group-tab:: C++ + + See also :cpp:func:`simgrid::s4u::Engine::get_all_hosts`. + + .. autodoxymethod:: simgrid::s4u::Host::by_name(const std::string &name) + .. autodoxymethod:: simgrid::s4u::Host::by_name_or_null(const std::string &name) + .. autodoxymethod:: simgrid::s4u::Host::current() + + .. group-tab:: Python + + See also :py:func:`simgrid.Engine.get_all_hosts`. + + .. automethod:: simgrid.Host.by_name + .. automethod:: simgrid.Host.current + + .. group-tab:: C + + .. autodoxymethod:: sg_host_by_name(const char *name) + .. autodoxymethod:: sg_host_count() + .. autodoxymethod:: sg_host_list() + .. autodoxymethod:: sg_hosts_as_dynar() + +Querying info +------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Host::get_cname() + .. autodoxymethod:: simgrid::s4u::Host::get_core_count() + .. autodoxymethod:: simgrid::s4u::Host::get_name() + .. autodoxymethod:: simgrid::s4u::Host::get_available_speed() + .. autodoxymethod:: simgrid::s4u::Host::get_load() + .. autodoxymethod:: simgrid::s4u::Host::get_speed() + + .. group-tab:: Python + + .. autoattribute:: simgrid.Host.name + .. autoattribute:: simgrid.Host.load + .. autoattribute:: simgrid.Host.pstate + .. autoattribute:: simgrid.Host.speed + + .. group-tab:: C + + .. autodoxymethod:: sg_host_core_count(const_sg_host_t host) + .. autodoxymethod:: sg_host_dump(const_sg_host_t ws) + .. autodoxymethod:: sg_host_get_name(const_sg_host_t host) + .. autodoxymethod:: sg_host_load(const_sg_host_t host) + .. autodoxymethod:: sg_host_speed(const_sg_host_t host) + +User data and properties +------------------------ + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Host::get_properties() + .. autodoxymethod:: simgrid::s4u::Host::get_property(const std::string &key) + .. autodoxymethod:: simgrid::s4u::Host::set_properties(const std::map< std::string, std::string > &properties) + .. autodoxymethod:: simgrid::s4u::Host::set_property(const std::string &key, const std::string &value) + + .. group-tab:: C + + .. autodoxymethod:: sg_host_set_property_value(sg_host_t host, const char *name, const char *value) + .. autodoxymethod:: sg_host_get_properties(const_sg_host_t host) + .. autodoxymethod:: sg_host_get_property_value(const_sg_host_t host, const char *name) + .. autodoxymethod:: sg_host_extension_create(void(*deleter)(void *)) + .. autodoxymethod:: sg_host_extension_get(const_sg_host_t host, size_t rank) + +Retrieving components +--------------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Host::add_disk(Disk *disk) + .. autodoxymethod:: simgrid::s4u::Host::get_actor_count() + .. autodoxymethod:: simgrid::s4u::Host::get_all_actors() + .. autodoxymethod:: simgrid::s4u::Host::get_disks() + .. autodoxymethod:: simgrid::s4u::Host::remove_disk(const std::string &disk_name) + + .. group-tab:: C + + .. autodoxymethod:: sg_host_get_actor_list(const_sg_host_t host, xbt_dynar_t whereto) + +On/Off +------ + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Host::is_on() + .. autodoxymethod:: simgrid::s4u::Host::turn_off() + .. autodoxymethod:: simgrid::s4u::Host::turn_on() + + .. group-tab:: C + + .. autodoxymethod:: sg_host_is_on(const_sg_host_t host) + .. autodoxymethod:: sg_host_turn_off(sg_host_t host) + .. autodoxymethod:: sg_host_turn_on(sg_host_t host) + +DVFS +---- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Host::get_pstate() + .. autodoxymethod:: simgrid::s4u::Host::get_pstate_count() + .. autodoxymethod:: simgrid::s4u::Host::get_pstate_speed(int pstate_index) + .. autodoxymethod:: simgrid::s4u::Host::set_pstate(int pstate_index) + .. autodoxymethod:: simgrid::s4u::Host::set_speed_profile(kernel::profile::Profile *p) + .. autodoxymethod:: simgrid::s4u::Host::set_state_profile(kernel::profile::Profile *p) + + .. group-tab:: Python + + .. automethod:: simgrid.Host.get_pstate_count + .. automethod:: simgrid.Host.get_pstate_speed + + .. group-tab:: C + + .. autodoxymethod:: sg_host_get_available_speed(const_sg_host_t host) + .. autodoxymethod:: sg_host_get_nb_pstates(const_sg_host_t host) + .. autodoxymethod:: sg_host_get_pstate(const_sg_host_t host) + .. autodoxymethod:: sg_host_get_pstate_speed(const_sg_host_t host, int pstate_index) + .. autodoxymethod:: sg_host_set_pstate(sg_host_t host, int pstate) + +Execution +--------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Host::exec_async(double flops_amounts) + .. autodoxymethod:: simgrid::s4u::Host::execute(double flops) + .. autodoxymethod:: simgrid::s4u::Host::execute(double flops, double priority) + +Platform and routing +-------------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Host::get_englobing_zone() + .. autodoxymethod:: simgrid::s4u::Host::get_netpoint() + .. autodoxymethod:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< Link * > &links, double *latency) + .. autodoxymethod:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< kernel::resource::LinkImpl * > &links, double *latency) + .. autodoxymethod:: simgrid::s4u::Host::send_to(Host *dest, double byte_amount) + + .. group-tab:: C + + .. autodoxymethod:: sg_host_route(const_sg_host_t from, const_sg_host_t to, xbt_dynar_t links) + .. autodoxymethod:: sg_host_route_bandwidth(const_sg_host_t from, const_sg_host_t to) + .. autodoxymethod:: sg_host_route_latency(const_sg_host_t from, const_sg_host_t to) + .. autodoxymethod:: sg_host_send_to(sg_host_t from, sg_host_t to, double byte_amount) + +Signals +------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxyvar:: simgrid::s4u::Host::on_creation + .. autodoxyvar:: simgrid::s4u::Host::on_destruction + .. autodoxyvar:: simgrid::s4u::Host::on_speed_change + .. autodoxyvar:: simgrid::s4u::Host::on_state_change + +.. _API_s4u_Link: + +============= +⁣  class Link +============= + +.. autodoxyclass:: simgrid::s4u::Link + +Basic management +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + Note that there is no LinkPtr type, and that you cannot use the RAII + idiom on hosts because SimGrid does not allow (yet) to create nor + destroy resources once the simulation is started. + + .. group-tab:: Python + + .. code:: Python + + from simgrid import Link + + .. group-tab:: C + + .. code:: C + + #include + + .. doxygentypedef:: sg_link_t + .. cpp:type:: const s4u_Link* const_sg_link_t + + Pointer to a constant link object. + +Retrieving links +---------------- + +.. tabs:: + + .. group-tab:: C++ + + See also :cpp:func:`simgrid::s4u::Engine::get_all_links`. + + .. autodoxymethod:: simgrid::s4u::Link::by_name(const std::string &name) + .. autodoxymethod:: simgrid::s4u::Link::by_name_or_null(const std::string &name) + + .. group-tab:: C + + .. autodoxymethod:: sg_link_by_name(const char *name) + .. autodoxymethod:: sg_link_count() + .. autodoxymethod:: sg_link_list() + +Querying info +-------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Link::get_bandwidth() + .. autodoxymethod:: simgrid::s4u::Link::get_cname() + .. autodoxymethod:: simgrid::s4u::Link::get_latency() + .. autodoxymethod:: simgrid::s4u::Link::get_name() + .. autodoxymethod:: simgrid::s4u::Link::get_sharing_policy() + .. autodoxymethod:: simgrid::s4u::Link::get_usage() + .. autodoxymethod:: simgrid::s4u::Link::is_used() + + .. group-tab:: C + + .. autodoxymethod:: sg_link_bandwidth(const_sg_link_t link) + .. autodoxymethod:: sg_link_is_shared(const_sg_link_t link) + .. autodoxymethod:: sg_link_latency(const_sg_link_t link) + .. autodoxymethod:: sg_link_name(const_sg_link_t link) + +User data and properties +------------------------ + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Link::get_property(const std::string &key) + .. autodoxymethod:: simgrid::s4u::Link::set_property(const std::string &key, const std::string &value) + + .. group-tab:: C + + .. autodoxymethod:: sg_link_data(const_sg_link_t link) + .. autodoxymethod:: sg_link_data_set(sg_link_t link, void *data) + +On/Off +------ + +.. tabs:: + + .. group-tab:: C++ + + See also :cpp:func:`simgrid::s4u::Link::set_state_profile`. + + .. autodoxymethod:: simgrid::s4u::Link::is_on() + .. autodoxymethod:: simgrid::s4u::Link::turn_off() + .. autodoxymethod:: simgrid::s4u::Link::turn_on() + +Dynamic profiles +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Link::set_bandwidth_profile(kernel::profile::Profile *profile) + .. autodoxymethod:: simgrid::s4u::Link::set_latency_profile(kernel::profile::Profile *profile) + .. autodoxymethod:: simgrid::s4u::Link::set_state_profile(kernel::profile::Profile *profile) + +Signals +------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxyvar:: simgrid::s4u::Link::on_bandwidth_change + .. cpp:var:: xbt::signal Link::on_communicate + .. autodoxyvar:: simgrid::s4u::Link::on_communication_state_change + .. autodoxyvar:: simgrid::s4u::Link::on_creation + .. autodoxyvar:: simgrid::s4u::Link::on_destruction + .. autodoxyvar:: simgrid::s4u::Link::on_state_change + +.. _API_s4u_NetZone: + +================ +⁣  class NetZone +================ + +.. autodoxyclass:: simgrid::s4u::NetZone + +Basic management +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + Note that there is no NetZonePtr type, and that you cannot use the RAII + idiom on network zones because SimGrid does not allow (yet) to create nor + destroy resources once the simulation is started. + + .. group-tab:: C + + .. code:: C + + #include + + .. doxygentypedef:: sg_netzone_t + .. cpp:type:: const s4u_NetZone* const_sg_netzone_t + + Pointer to a constant network zone object. + +Retrieving zones +---------------- + +.. tabs:: + + .. group-tab:: C++ + + See :cpp:func:`simgrid::s4u::Engine::get_netzone_root`, + :cpp:func:`simgrid::s4u::Engine::netzone_by_name_or_null` and + :cpp:func:`simgrid::s4u::Engine::get_filtered_netzones`. + + .. group-tab:: C + + .. autodoxymethod:: sg_zone_get_by_name(const char *name) + .. autodoxymethod:: sg_zone_get_root() + +Querying info +-------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::NetZone::get_cname() + .. autodoxymethod:: simgrid::s4u::NetZone::get_name() + + .. group-tab:: C + + .. autodoxymethod:: sg_zone_get_name(const_sg_netzone_t zone) + +User data and properties +------------------------ + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::NetZone::get_properties() + .. autodoxymethod:: simgrid::s4u::NetZone::get_property(const std::string &key) + .. autodoxymethod:: simgrid::s4u::NetZone::set_property(const std::string &key, const std::string &value) + + .. group-tab:: C + + .. autodoxymethod:: sg_zone_get_property_value(const_sg_netzone_t as, const char *name) + .. autodoxymethod:: sg_zone_set_property_value(sg_netzone_t netzone, const char *name, const char *value) + +Retrieving components +--------------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::NetZone::get_all_hosts() + .. autodoxymethod:: simgrid::s4u::NetZone::get_host_count() + + .. group-tab:: C + + .. autodoxymethod:: sg_zone_get_hosts(const_sg_netzone_t zone, xbt_dynar_t whereto) + +Routing data +------------ + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::NetZone::add_bypass_route(kernel::routing::NetPoint *src, kernel::routing::NetPoint *dst, kernel::routing::NetPoint *gw_src, kernel::routing::NetPoint *gw_dst, std::vector< kernel::resource::LinkImpl * > &link_list, bool symmetrical) + .. autodoxymethod:: simgrid::s4u::NetZone::add_component(kernel::routing::NetPoint *elm) + .. autodoxymethod:: simgrid::s4u::NetZone::add_route(kernel::routing::NetPoint *src, kernel::routing::NetPoint *dst, kernel::routing::NetPoint *gw_src, kernel::routing::NetPoint *gw_dst, std::vector< kernel::resource::LinkImpl * > &link_list, bool symmetrical) + .. autodoxymethod:: simgrid::s4u::NetZone::get_children() + .. autodoxymethod:: simgrid::s4u::NetZone::get_father() + + .. group-tab:: C + + .. autodoxymethod:: sg_zone_get_sons(const_sg_netzone_t zone, xbt_dict_t whereto) + +Signals +------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxyvar:: simgrid::s4u::NetZone::on_creation + .. autodoxyvar:: simgrid::s4u::NetZone::on_route_creation + .. autodoxyvar:: simgrid::s4u::NetZone::on_seal + + +.. doxygenclass:: simgrid::s4u::NetZone + :members: + :protected-members: + :undoc-members: + +.. _API_s4u_VirtualMachine: + +======================= +⁣  class VirtualMachine +======================= + + +.. autodoxyclass:: simgrid::s4u::VirtualMachine + +Basic management +---------------- +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + Note that there is no VirtualMachinePtr type, and that you cannot use the RAII + idiom on virtual machines. There is no good reason for that and should change in the future. + + .. group-tab:: C + + .. code:: C + + #include + + .. doxygentypedef:: sg_vm_t + .. cpp:type:: const s4u_VirtualMachine* const_sg_vm_t + + Pointer to a constant virtual machine object. + +Creating VMs +------------ + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::VirtualMachine::VirtualMachine(const std::string &name, Host *physical_host, int core_amount) + .. autodoxymethod:: simgrid::s4u::VirtualMachine::VirtualMachine(const std::string &name, Host *physical_host, int core_amount, size_t ramsize) + .. autodoxymethod:: simgrid::s4u::VirtualMachine::destroy() + + .. group-tab:: C + + .. autodoxymethod:: sg_vm_create_core + .. autodoxymethod:: sg_vm_create_multicore + .. autodoxymethod:: sg_vm_destroy + +Querying info +-------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::VirtualMachine::get_pm() + .. autodoxymethod:: simgrid::s4u::VirtualMachine::get_ramsize() + .. autodoxymethod:: simgrid::s4u::VirtualMachine::get_state() + + .. autodoxymethod:: simgrid::s4u::VirtualMachine::set_bound(double bound) + .. autodoxymethod:: simgrid::s4u::VirtualMachine::set_pm(Host *pm) + .. autodoxymethod:: simgrid::s4u::VirtualMachine::set_ramsize(size_t ramsize) + + .. group-tab:: C + + .. autodoxymethod:: sg_vm_get_ramsize(const_sg_vm_t vm) + .. autodoxymethod:: sg_vm_set_bound(sg_vm_t vm, double bound) + .. autodoxymethod:: sg_vm_set_ramsize(sg_vm_t vm, size_t size) + + .. 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 + +Life cycle +---------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::VirtualMachine::resume() + .. autodoxymethod:: simgrid::s4u::VirtualMachine::shutdown() + .. autodoxymethod:: simgrid::s4u::VirtualMachine::start() + .. autodoxymethod:: simgrid::s4u::VirtualMachine::suspend() + + .. group-tab:: C + + .. autodoxymethod:: sg_vm_start + .. autodoxymethod:: sg_vm_suspend + .. autodoxymethod:: sg_vm_resume + .. autodoxymethod:: sg_vm_shutdown + +Signals +------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxyvar:: simgrid::s4u::VirtualMachine::on_migration_end + .. autodoxyvar:: simgrid::s4u::VirtualMachine::on_migration_start + .. autodoxyvar:: simgrid::s4u::VirtualMachine::on_resume + .. autodoxyvar:: simgrid::s4u::VirtualMachine::on_shutdown + .. autodoxyvar:: simgrid::s4u::VirtualMachine::on_start + .. autodoxyvar:: simgrid::s4u::VirtualMachine::on_started + .. autodoxyvar:: simgrid::s4u::VirtualMachine::on_suspend + +.. _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. + +Querying info +------------- + + .. autodoxymethod:: simgrid::s4u::Activity::get_remaining() + .. autodoxymethod:: simgrid::s4u::Activity::get_state() + .. autodoxymethod:: simgrid::s4u::Activity::set_remaining(double remains) + +Activities life cycle +--------------------- + + .. 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) + .. autodoxymethod:: simgrid::s4u::Activity::vetoable_start() + +.. _API_s4u_Comm: + +============= +⁣  class Comm +============= + +.. doxygentypedef:: CommPtr + +.. doxygenclass:: simgrid::s4u::Comm + :members: + :protected-members: + :undoc-members: + +.. _API_s4u_Exec: + +============= +⁣  class Exec +============= + +.. doxygentypedef:: ExecPtr + +.. doxygenclass:: simgrid::s4u::Exec + :members: + :protected-members: + :undoc-members: + +.. _API_s4u_ExecSeq: + +================== +⁣    class ExecSeq +================== + +.. doxygentypedef:: ExecSeqPtr + +.. doxygenclass:: simgrid::s4u::ExecSeq + :members: + :protected-members: + :undoc-members: + +.. _API_s4u_ExecPar: + +================== +⁣    class ExecPar +================== + +.. doxygentypedef:: ExecParPtr + +.. doxygenclass:: simgrid::s4u::ExecPar + :members: + :protected-members: + :undoc-members: + +.. _API_s4u_Io: + +=========== +⁣  class Io +=========== + +.. doxygentypedef:: IoPtr + +.. doxygenclass:: simgrid::s4u::Io + :members: + :protected-members: + :undoc-members: + +.. _API_s4u_Synchronizations: ======================= Synchronization Objects ======================= +.. _API_s4u_Mutex: + +============== +⁣  Mutex +============== + +.. autodoxyclass:: simgrid::s4u::Mutex + +Basic management +---------------- + + .. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + .. doxygentypedef:: MutexPtr + + .. autodoxymethod:: simgrid::s4u::Mutex::Mutex(kernel::activity::MutexImpl *mutex) + .. autodoxymethod:: simgrid::s4u::Mutex::create() + .. autodoxymethod:: simgrid::s4u::Mutex::~Mutex() + + .. group-tab:: C + + .. code-block:: C + + #include + + .. doxygentypedef:: sg_mutex_t + .. cpp:type:: const s4u_Mutex* const_sg_mutex_t + + Pointer to a constant mutex object. + + .. autodoxymethod:: sg_mutex_init() + .. autodoxymethod:: sg_mutex_destroy(const_sg_mutex_t mutex) + +Locking +------- + + .. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Mutex::lock() + .. autodoxymethod:: simgrid::s4u::Mutex::try_lock() + .. autodoxymethod:: simgrid::s4u::Mutex::unlock() + + .. 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: ================ @@ -962,7 +1841,7 @@ Synchronization Objects .. doxygentypedef:: sg_bar_t .. cpp:type:: const s4u_Barrier* const_sg_bar_t - Constant pointer to a SimGrid barrier object. + Pointer to a constant barrier object. .. autodoxymethod:: sg_barrier_init(unsigned int count) .. autodoxymethod:: sg_barrier_destroy(const_sg_bar_t bar) @@ -1030,72 +1909,65 @@ Waiting and notifying .. doxygenfunction:: sg_cond_wait .. doxygenfunction:: sg_cond_wait_for -.. _API_s4u_Mutex: +.. _API_s4u_Semaphore: -============== -⁣  class Mutex -============== +================== +⁣  Semaphore +================== -.. doxygentypedef:: MutexPtr +.. autodoxyclass:: simgrid::s4u::Semaphore -.. doxygenclass:: simgrid::s4u::Mutex - :members: - :protected-members: - :undoc-members: -.. _API_s4u_Semaphore: +Basic management +---------------- -================== -⁣  class Semaphore -================== + .. tabs:: -.. doxygentypedef:: SemaphorePtr + .. group-tab:: C++ -.. doxygenclass:: simgrid::s4u::Semaphore - :members: - :protected-members: - :undoc-members: + .. code-block:: C++ -Python API Reference -******************** + #include -The Python API is automatically generated with pybind11. It closely mimicks the C++ -API, to which you should refer for more information. + .. 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) -========== -this_actor -========== + .. group-tab:: C -.. automodule:: simgrid.this_actor - :members: + .. code-block:: C -========== -Class Comm -========== + #include -.. autoclass:: simgrid.Comm - :members: + .. doxygentypedef:: sg_sem_t + .. cpp:type:: const s4u_Semaphore* const_sg_sem_t -========== -Class Exec -========== + Pointer to a constant semaphore object. -.. autoclass:: simgrid.Exec - :members: + .. autodoxymethod:: sg_sem_init(int initial_value) + .. autodoxymethod:: sg_sem_destroy(const_sg_sem_t sem) -========== -Class Host -========== +Locking +------- -.. autoclass:: simgrid.Host - :members: + .. tabs:: -============= -Class Mailbox -============= + .. group-tab:: C++ -.. autoclass:: simgrid.Mailbox - :members: + .. 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) .. |hr| raw:: html