X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/88da900bc8d43401167e64b7f55c49be6164c85f..08eb681376f0a99c445234cc8e4cc9ae2e0b00e5:/docs/source/app_s4u.rst diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index a605c7ac4e..cd7d1abea3 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -334,6 +334,26 @@ that are 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 an on_exit callback. +=============================== +Communicating without Mailboxes +=============================== + +Sometimes you don't want to simulate communications between actors as +allowed by mailboxes, but you want to create a direct communication +between two arbitrary hosts. This can arise when you write a +high-level model of a centralized scheduler, or when you model direct +communications such as one-sided communications in MPI or remote +memory direct access in PGAS. + +For that, :cpp:func:`Comm::sendto() ` +simulates a direct communication between the two specified hosts. No +mailbox is used, and there is no rendezvous between actors. You can +freely mix such direct communications and rendezvous-based +communications. Alternatively, :cpp:func:`Comm::sendto_init() +` and +:cpp:func:`Comm::sendto_async() ` +create asynchronous direct communications. + .. _s4u_raii: Memory Management @@ -409,6 +429,8 @@ Basic management from simgrid import Actor + .. autoclass:: simgrid.Actor + .. group-tab:: C .. code:: C @@ -416,10 +438,7 @@ Basic management #include .. doxygentypedef:: sg_actor_t - .. cpp:type:: const s4u_Actor* const_sg_actor_t - - Pointer to a constant actor object. - + .. doxygentypedef:: const_sg_actor_t .. doxygenfunction:: sg_actor_ref .. doxygenfunction:: sg_actor_unref @@ -438,6 +457,7 @@ Creating actors .. doxygenfunction:: simgrid::s4u::Actor::init(const std::string &name, s4u::Host *host) .. doxygenfunction:: simgrid::s4u::Actor::start(const std::function< void()> &code) + .. doxygenfunction:: simgrid::s4u::Actor::set_stacksize .. group-tab:: Python @@ -445,9 +465,10 @@ Creating actors .. group-tab:: C - .. doxygenfunction:: sg_actor_create(const char *name, sg_host_t host, xbt_main_func_t code, int argc, const char *const *argv) + .. doxygenfunction:: sg_actor_create(const char *name, sg_host_t host, xbt_main_func_t code, int argc, char *const *argv) .. doxygenfunction:: sg_actor_init(const char *name, sg_host_t host) - .. doxygenfunction:: sg_actor_start(sg_actor_t actor, xbt_main_func_t code, int argc, const char *const *argv) + .. doxygenfunction:: sg_actor_start(sg_actor_t actor, xbt_main_func_t code, int argc, char *const *argv) + .. doxygenfunction:: sg_actor_set_stacksize .. doxygenfunction:: sg_actor_attach(const char *name, void *data, sg_host_t host, xbt_dict_t properties) .. doxygenfunction:: sg_actor_detach() @@ -469,7 +490,7 @@ Retrieving actors .. group-tab:: C - .. doxygenfunction:: sg_actor_by_PID(aid_t pid) + .. doxygenfunction:: sg_actor_by_pid(aid_t pid) .. doxygenfunction:: sg_actor_self() Querying info @@ -503,8 +524,8 @@ Querying info .. group-tab:: C .. doxygenfunction:: sg_actor_get_name(const_sg_actor_t actor) - .. doxygenfunction:: sg_actor_get_PID(const_sg_actor_t actor) - .. doxygenfunction:: sg_actor_get_PPID(const_sg_actor_t actor) + .. doxygenfunction:: sg_actor_get_pid(const_sg_actor_t actor) + .. doxygenfunction:: sg_actor_get_ppid(const_sg_actor_t actor) .. doxygenfunction:: sg_actor_get_properties(const_sg_actor_t actor) .. doxygenfunction:: sg_actor_get_property_value(const_sg_actor_t actor, const char *name) @@ -591,6 +612,7 @@ Reacting to the end of actors .. group-tab:: C + .. doxygenfunction:: sg_actor_on_exit .. doxygenfunction:: sg_actor_join(const_sg_actor_t actor, double timeout) .. doxygenfunction:: sg_actor_set_auto_restart(sg_actor_t actor, int auto_restart) @@ -748,6 +770,12 @@ Exiting .. autofunction:: simgrid.this_actor.exit .. autofunction:: simgrid.this_actor.on_exit + .. group-tab:: c + + See also :cpp:func:`sg_actor_on_exit`. + + .. doxygenfunction:: sg_actor_exit + .. _API_s4u_Engine: ==================== @@ -925,15 +953,24 @@ Basic management .. group-tab:: Python + .. code-block:: C++ + + #include + + .. autoclass:: simgrid.Mailbox + .. automethod:: simgrid.Mailbox.by_name + .. group-tab:: C + .. code-block:: C #include - .. doxygenfunction:: sg_mailbox_by_name(const char *alias) + .. doxygentypedef:: sg_mailbox_t + .. doxygentypedef:: const_sg_mailbox_t - .. group-tab:: C + .. doxygenfunction:: sg_mailbox_by_name(const char *alias) Querying info ------------- @@ -967,7 +1004,7 @@ Sending data .. automethod:: simgrid.Mailbox.put .. automethod:: simgrid.Mailbox.put_async - .. group-tab: C + .. group-tab:: C .. doxygenfunction:: sg_mailbox_put(sg_mailbox_t mailbox, void *payload, long simulated_size_in_bytes) .. doxygenfunction:: sg_mailbox_put_init(sg_mailbox_t mailbox, void *payload, long simulated_size_in_bytes) @@ -1071,11 +1108,11 @@ I/O operations .. group-tab:: C++ - .. doxygenfunction:: simgrid::s4u::Disk::io_init(sg_size_t size, s4u::Io::OpType type) - .. doxygenfunction:: simgrid::s4u::Disk::read(sg_size_t size) - .. doxygenfunction:: simgrid::s4u::Disk::read_async(sg_size_t size) - .. doxygenfunction:: simgrid::s4u::Disk::write(sg_size_t size) - .. doxygenfunction:: simgrid::s4u::Disk::write_async(sg_size_t size) + .. doxygenfunction:: simgrid::s4u::Disk::io_init(sg_size_t size, s4u::Io::OpType type) const + .. doxygenfunction:: simgrid::s4u::Disk::read(sg_size_t size) const + .. doxygenfunction:: simgrid::s4u::Disk::read_async(sg_size_t size) const + .. doxygenfunction:: simgrid::s4u::Disk::write(sg_size_t size) const + .. doxygenfunction:: simgrid::s4u::Disk::write_async(sg_size_t size) const Signals ------- @@ -1282,16 +1319,17 @@ Execution Platform and routing -------------------- +You can also start direct communications between two arbitrary hosts +using :cpp:func:`Comm::sendto() `. + .. tabs:: .. group-tab:: C++ - .. doxygenfunction:: simgrid::s4u::Host::get_englobing_zone() + .. doxygenfunction:: simgrid::s4u::Host::get_englobing_zone() const .. doxygenfunction:: simgrid::s4u::Host::get_netpoint() const .. doxygenfunction:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< Link * > &links, double *latency) const .. doxygenfunction:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< kernel::resource::LinkImpl * > &links, double *latency) const - .. doxygenfunction:: simgrid::s4u::Host::sendto(Host *dest, double byte_amount) - .. doxygenfunction:: simgrid::s4u::Host::sendto_async(Host *dest, double byte_amount) .. group-tab:: C @@ -1319,6 +1357,8 @@ Signals ============= .. doxygenclass:: simgrid::s4u::Link +.. doxygenclass:: simgrid::s4u::SplitDuplexLink +.. doxygenclass:: simgrid::s4u::LinkInRoute Basic management ---------------- @@ -1572,11 +1612,11 @@ Routing data .. group-tab:: C++ - .. doxygenfunction:: simgrid::s4u::NetZone::add_bypass_route .. doxygenfunction:: simgrid::s4u::NetZone::add_component(kernel::routing::NetPoint *elm) .. doxygenfunction:: simgrid::s4u::NetZone::add_route + .. doxygenfunction:: simgrid::s4u::NetZone::add_bypass_route .. doxygenfunction:: simgrid::s4u::NetZone::get_children() const - .. doxygenfunction:: simgrid::s4u::NetZone::get_father() + .. doxygenfunction:: simgrid::s4u::NetZone::get_parent() const .. group-tab:: C @@ -1590,7 +1630,6 @@ Signals .. group-tab:: C++ .. doxygenvariable:: simgrid::s4u::NetZone::on_creation - .. doxygenvariable:: simgrid::s4u::NetZone::on_route_creation .. doxygenvariable:: simgrid::s4u::NetZone::on_seal .. _API_s4u_VirtualMachine: @@ -1799,6 +1838,17 @@ Basic management from simgrid import Comm + .. autoclass:: simgrid.Comm + + .. group-tab:: c + + .. code:: c + + #include + + .. doxygentypedef:: sg_comm_t + .. doxygentypedef:: const_sg_comm_t + Querying info ------------- @@ -1813,6 +1863,7 @@ Querying info .. doxygenfunction:: simgrid::s4u::Comm::set_dst_data(void **buff, size_t size) .. doxygenfunction:: simgrid::s4u::Comm::detach() .. doxygenfunction:: simgrid::s4u::Comm::detach(void(*clean_function)(void *)) + .. doxygenfunction:: simgrid::s4u::Comm::set_payload_size(double bytes) .. doxygenfunction:: simgrid::s4u::Comm::set_rate(double rate) .. doxygenfunction:: simgrid::s4u::Comm::set_src_data(void *buff) .. doxygenfunction:: simgrid::s4u::Comm::set_src_data(void *buff, size_t size) @@ -1821,26 +1872,41 @@ Querying info Life cycle ---------- +Most communications are created using :ref:`s4u_mailbox`, but you can +also start direct communications as shown below. + .. tabs:: .. group-tab:: C++ + .. doxygenfunction:: simgrid::s4u::Comm::sendto + .. doxygenfunction:: simgrid::s4u::Comm::sendto_init + .. doxygenfunction:: simgrid::s4u::Comm::sendto_async + .. doxygenfunction:: simgrid::s4u::Comm::cancel .. doxygenfunction:: simgrid::s4u::Comm::start .. doxygenfunction:: simgrid::s4u::Comm::test - .. doxygenfunction:: simgrid::s4u::Comm::test_any(const std::vector< CommPtr > *comms) + .. doxygenfunction:: simgrid::s4u::Comm::test_any(const std::vector< CommPtr >& comms) .. doxygenfunction:: simgrid::s4u::Comm::wait - .. doxygenfunction:: simgrid::s4u::Comm::wait_all(const std::vector< CommPtr > *comms) - .. doxygenfunction:: simgrid::s4u::Comm::wait_any(const std::vector< CommPtr > *comms) - .. doxygenfunction:: simgrid::s4u::Comm::wait_any_for(const std::vector< CommPtr > *comms_in, double timeout) + .. doxygenfunction:: simgrid::s4u::Comm::wait_all(const std::vector< CommPtr >& comms) + .. doxygenfunction:: simgrid::s4u::Comm::wait_all_for(const std::vector< CommPtr >& comms, double timeout) + .. doxygenfunction:: simgrid::s4u::Comm::wait_any(const std::vector< CommPtr >& comms) + .. doxygenfunction:: simgrid::s4u::Comm::wait_any_for(const std::vector< CommPtr >& comms, double timeout) .. doxygenfunction:: simgrid::s4u::Comm::wait_for .. group-tab:: Python - .. automethod:: simgrid.Comm.test - .. automethod:: simgrid.Comm.wait - .. automethod:: simgrid.Comm.wait_all - .. automethod:: simgrid.Comm.wait_any + .. automethod:: simgrid.Comm.test + .. automethod:: simgrid.Comm.wait + .. automethod:: simgrid.Comm.wait_all + .. automethod:: simgrid.Comm.wait_any + + .. group-tab:: C + + .. doxygenfunction:: sg_comm_test + .. doxygenfunction:: sg_comm_wait + .. doxygenfunction:: sg_comm_wait_all + .. doxygenfunction:: sg_comm_wait_any Signals ------- @@ -1878,13 +1944,18 @@ Basic management .. code:: Python from simgrid import Exec - + + .. autoclass:: simgrid.Exec + .. group-tab:: C .. code-block:: C #include + .. doxygentypedef:: sg_exec_t + .. doxygentypedef:: const_sg_exec_t + Querying info ------------- @@ -1896,11 +1967,7 @@ Querying info .. doxygenfunction:: simgrid::s4u::Exec::get_finish_time() const .. doxygenfunction:: simgrid::s4u::Exec::get_host() const .. doxygenfunction:: simgrid::s4u::Exec::get_host_number() const - .. cpp:function:: double Exec::get_remaining() - - On sequential executions, returns the amount of flops that remain to be done; - This cannot be used on parallel executions. - + .. doxygenfunction:: simgrid::s4u::Exec::get_remaining .. doxygenfunction:: simgrid::s4u::Exec::get_remaining_ratio .. doxygenfunction:: simgrid::s4u::Exec::get_start_time() const .. doxygenfunction:: simgrid::s4u::Exec::set_bound(double bound) @@ -1930,12 +1997,11 @@ Life cycle .. group-tab:: C++ .. doxygenfunction:: simgrid::s4u::Exec::cancel - .. doxygenfunction:: simgrid::s4u::Exec::set_timeout(double timeout) .. doxygenfunction:: simgrid::s4u::Exec::start .. doxygenfunction:: simgrid::s4u::Exec::test .. doxygenfunction:: simgrid::s4u::Exec::wait - .. doxygenfunction:: simgrid::s4u::Exec::wait_any(std::vector< ExecPtr > *execs) - .. doxygenfunction:: simgrid::s4u::Exec::wait_any_for(std::vector< ExecPtr > *execs, double timeout) + .. doxygenfunction:: simgrid::s4u::Exec::wait_any(const std::vector< ExecPtr >& execs) + .. doxygenfunction:: simgrid::s4u::Exec::wait_any_for(const std::vector< ExecPtr >& execs, double timeout) .. doxygenfunction:: simgrid::s4u::Exec::wait_for .. group-tab:: Python @@ -2036,9 +2102,7 @@ Basic management .. doxygentypedef:: MutexPtr - .. doxygenfunction:: simgrid::s4u::Mutex::Mutex(kernel::activity::MutexImpl *mutex) .. doxygenfunction:: simgrid::s4u::Mutex::create() - .. doxygenfunction:: simgrid::s4u::Mutex::~Mutex() .. group-tab:: C @@ -2139,6 +2203,7 @@ Basic management #include .. doxygentypedef:: sg_cond_t + .. doxygentypedef:: const_sg_cond_t .. doxygenfunction:: sg_cond_init .. doxygenfunction:: sg_cond_destroy @@ -2191,8 +2256,6 @@ Basic management #include .. doxygentypedef:: SemaphorePtr - .. doxygenfunction:: simgrid::s4u::Semaphore::Semaphore(unsigned int initial_capacity) - .. doxygenfunction:: simgrid::s4u::Semaphore::~Semaphore() .. doxygenfunction:: simgrid::s4u::Semaphore::create(unsigned int initial_capacity) .. group-tab:: C