.. _S4U_doc:
+=================
The S4U Interface
=================
abstract algorithms in the domains of Cloud, P2P, HPC, IoT and similar
settings.
+-------------
Main Concepts
-------------
.. |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 <exhale_class_classsimgrid_1_1s4u_1_1Comm>` that
+consumes the *transmiting power* of :ref:`s4u::Link
+<exhale_class_classsimgrid_1_1s4u_1_1Link>` resources. Every activity
+can be either **blocking** or **asynchronous**. For example,
+:cpp:func:`s4u::Mailbox::put() <simgrid::s4u::Mailbox::put>` and
+:cpp:func:`s4u::Mailbox::get() <simgrid::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() <simgrid::s4u::Mailbox::put_async>`.
+Finally, the actor waits for the completion of all of them at once
+with
+:cpp:func:`s4u::Comm::wait_all() <simgrid::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 <exhale_class_classsimgrid_1_1s4u_1_1Comm>` are created with
+ :cpp:func:`s4u::Mailbox::put_async() <simgrid::s4u::Mailbox::put_async>` and
+ :cpp:func:`s4u::Mailbox::get_async() <simgrid::s4u::Mailbox::get_async>`.
+ - :ref:`s4u::IoPtr <exhale_class_classsimgrid_1_1s4u_1_1Io>` are created with
+ :cpp:func:`s4u::Storage::read_async() <simgrid::s4u::Storage::read_async>` and
+ :cpp:func:`s4u::Storage::write_async() <simgrid::s4u::Storage::write_async>`.
+ - :ref:`s4u::ExecPtr <exhale_class_classsimgrid_1_1s4u_1_1Exec>` are created with
+ :cpp:func:`s4u::Host::exec_async() <simgrid::s4u::Host::exec_async>`.
+ - In the future, it will become possible to have asynchronous IPC
+ such as asynchronous mutex lock requests.
}
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<simgrid::s4u::CommPtr> pending_comms;
+ /* Make a vector of the mailboxes to use */
+ std::vector<simgrid::s4u::MailboxPtr> 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!");
}
