From: Martin Quinson Date: Fri, 24 Aug 2018 12:13:42 +0000 (+0200) Subject: docs: present asynchronous activities X-Git-Tag: v3_21~194 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/ac3767af4bf9250b301870faf01140dd39676a4f docs: present asynchronous activities --- diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index dd610a0a45..82a0785bde 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -1,5 +1,6 @@ .. _S4U_doc: +================= The S4U Interface ================= @@ -20,6 +21,7 @@ with the full power of C++. This is the prefered interface to describe abstract algorithms in the domains of Cloud, P2P, HPC, IoT and similar settings. +------------- Main Concepts ------------- @@ -129,3 +131,52 @@ functions to simplify the code of actors. .. |Mutex| replace:: **Mutex** .. _Mutex: api/classsimgrid_1_1s4u_1_1Mutex.html + +----------------------- +Asynchronous Activities +----------------------- + +Activities represent the actions that consumes a resource, such as +:ref:`s4u::Comm ` that +consumes the *transmiting power* of :ref:`s4u::Link +` resources. Every activity +can be either **blocking** or **asynchronous**. For example, +:cpp:func:`s4u::Mailbox::put() ` and +:cpp:func:`s4u::Mailbox::get() ` create +blocking communications: the actor is blocked until the completion of +that communication. Asynchronous communications do not block the actor +during their execution. The following example shows how to have +several concurrent communications ongoing. First, you have to declare +a vector in which we will store the ongoing communications. It is also +useful to have a vector of mailboxes. + +.. literalinclude:: ../../examples/s4u/async-waitall/s4u-async-waitall.cpp + :language: c++ + :start-after: init-begin + :end-before: init-end + :dedent: 4 + +You then start all communications that should occur concurrently with +:cpp:func:`s4u::Mailbox::put_async() `. +Finally, the actor waits for the completion of all of them at once +with +:cpp:func:`s4u::Comm::wait_all() `. + +.. literalinclude:: ../../examples/s4u/async-waitall/s4u-async-waitall.cpp + :language: c++ + :start-after: send-begin + :end-before: send-end + :dedent: 4 + +Every kind of activities can be asynchronous: + + - :ref:`s4u::CommPtr ` are created with + :cpp:func:`s4u::Mailbox::put_async() ` and + :cpp:func:`s4u::Mailbox::get_async() `. + - :ref:`s4u::IoPtr ` are created with + :cpp:func:`s4u::Storage::read_async() ` and + :cpp:func:`s4u::Storage::write_async() `. + - :ref:`s4u::ExecPtr ` are created with + :cpp:func:`s4u::Host::exec_async() `. + - In the future, it will become possible to have asynchronous IPC + such as asynchronous mutex lock requests. diff --git a/examples/s4u/async-waitall/s4u-async-waitall.cpp b/examples/s4u/async-waitall/s4u-async-waitall.cpp index 6ac940dcf0..514c69edb8 100644 --- a/examples/s4u/async-waitall/s4u-async-waitall.cpp +++ b/examples/s4u/async-waitall/s4u-async-waitall.cpp @@ -34,37 +34,42 @@ public: } void operator()() { + // sphinx-doc: init-begin (this line helps the doc to build; ignore it) + /* Vector in which we store all ongoing communications */ std::vector pending_comms; + /* Make a vector of the mailboxes to use */ + std::vector mboxes; + for (int i = 0; i < receivers_count; i++) + mboxes.push_back(simgrid::s4u::Mailbox::by_name(std::string("receiver-") + std::to_string(i))); + // sphinx-doc: init-end + /* Start dispatching all messages to receivers, in a round robin fashion */ for (int i = 0; i < messages_count; i++) { - std::string mboxName = std::string("receiver-") + std::to_string(i % receivers_count); - simgrid::s4u::MailboxPtr mbox = simgrid::s4u::Mailbox::by_name(mboxName); - std::string msgName = std::string("Message ") + std::to_string(i); - std::string* payload = new std::string(msgName); // copy the data we send: - // 'msgName' is not a stable storage location - XBT_INFO("Send '%s' to '%s'", msgName.c_str(), mboxName.c_str()); - /* Create a communication representing the ongoing communication */ - simgrid::s4u::CommPtr comm = mbox->put_async(payload, msg_size); - /* Add this comm to the vector of all known comms */ + std::string msg_content = std::string("Message ") + std::to_string(i); + // Copy the data we send: 'msg_content' is not a stable storage location. + // It will be destroyed when this actor leaves the loop, ie before the receiver gets it + std::string* payload = new std::string(msg_content); + + XBT_INFO("Send '%s' to '%s'", msg_content.c_str(), mboxes[i % receivers_count]->get_cname()); + + /* Create a communication representing the ongoing communication, and store it in pending_comms */ + simgrid::s4u::CommPtr comm = mboxes[i % receivers_count]->put_async(payload, msg_size); pending_comms.push_back(comm); } - /* Start sending messages to let the workers know that they should stop */ + /* Start sending messages to let the workers know that they should stop */ // sphinx-doc: send-begin for (int i = 0; i < receivers_count; i++) { - std::string mboxName = std::string("receiver-") + std::to_string(i % receivers_count); - simgrid::s4u::MailboxPtr mbox = simgrid::s4u::Mailbox::by_name(mboxName); - std::string* payload = new std::string("finalize"); // Make a copy of the data we will send - - simgrid::s4u::CommPtr comm = mbox->put_async(payload, 0); + XBT_INFO("Send 'finalize' to 'receiver-%d'", i); + simgrid::s4u::CommPtr comm = mboxes[i]->put_async(new std::string("finalize"), 0); pending_comms.push_back(comm); - XBT_INFO("Send 'finalize' to 'receiver-%ld'", i % receivers_count); } XBT_INFO("Done dispatching all messages"); /* Now that all message exchanges were initiated, wait for their completion in one single call */ simgrid::s4u::Comm::wait_all(&pending_comms); + // sphinx-doc: send-end XBT_INFO("Goodbye now!"); }