X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/18278c24522cdb44cb578759dc34a1b39f591e22..02c2b58c214aee79feb20427c6e0a511482bea35:/docs/source/app_s4u.rst diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 5828cfb3a7..8b0c009d21 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -429,6 +429,11 @@ Creating actors #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) @@ -600,9 +605,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: @@ -746,12 +871,106 @@ 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: +Basic management +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #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 + + .. automethod:: simgrid.Mailbox.by_name + +Querying info +............. + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Mailbox::get_cname() + .. autodoxymethod:: simgrid::s4u::Mailbox::get_name() + + .. group-tab:: Python + + .. autoattribute:: simgrid.Mailbox.name + +Sending data +............ + +.. tabs:: + + .. group-tab:: C++ + + .. 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) + + .. group-tab:: Python + + .. automethod:: simgrid.Mailbox.put + .. automethod:: simgrid.Mailbox.put_async + + +Receiving data +.............. + +.. tabs:: + + .. group-tab:: C++ + + .. 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() + + .. group-tab:: Python + + .. automethod:: simgrid.Mailbox.get + + .. group-tab:: C + + .. autodoxymethod:: sg_mailbox_listen(const char *alias) + +Receiving actor +............... + +See :ref:`s4u_receiving_actor`. + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Mailbox::get_receiver() + .. autodoxymethod:: simgrid::s4u::Mailbox::set_receiver(ActorPtr actor) + + .. group-tab:: C + + .. autodoxymethod:: ::sg_mailbox_set_receiver(const char *alias) + .. _API_s4u_Resource: ========= @@ -931,24 +1150,99 @@ Activities lifecycle 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: ================ -⁣  class Barrier +⁣  Barrier ================ -.. doxygentypedef:: BarrierPtr - .. 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: @@ -965,7 +1259,7 @@ Basic management .. group-tab:: C++ - .. code-block:: C + .. code-block:: C++ #include @@ -1011,31 +1305,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++ + + #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 ********************