src/msg/msg_mailbox.h

   1 /* Copyright (c) 2008-2015. The SimGrid Team.
   2  * All rights reserved.                                                     */
   3
   4 /* This program is free software; you can redistribute it and/or modify it
   5  * under the terms of the license (GNU LGPL) which comes with this package. */
   6
   7 #ifndef MSG_MAILBOX_H
   8 #define MSG_MAILBOX_H
   9
  10 #include <xbt/base.h>
  11 #include "xbt/fifo.h"
  12 #include "simgrid/simix.h"
  13 #include "simgrid/msg.h"
  14
  15
  16 SG_BEGIN_DECL()
  17 #define MAX_ALIAS_NAME  ((size_t)260)
  18
  19 /*! \brief MSG_mailbox_new - create a new mailbox.
  20  *
  21  * The function MSG_mailbox_new creates a new mailbox identified by the key specified
  22  * by the parameter alias and add it in the global dictionary.
  23  *
  24  * \param alias    The alias of the mailbox to create.
  25  *
  26  * \return    The newly created mailbox.
  27  */
  28 XBT_PUBLIC(msg_mailbox_t)
  29     MSG_mailbox_new(const char *alias);
  30
  31 XBT_PRIVATE void MSG_mailbox_free(void *mailbox);
  32
  33 /* \brief MSG_mailbox_free - release a mailbox from the memory.
  34  *
  35  * The function MSG_mailbox_free release a mailbox from the memory but does
  36  * not remove it from the dictionary.
  37  *
  38  * \param mailbox  The mailbox to release.
  39  *
  40  * \see      MSG_mailbox_destroy.
  41  */
  42 XBT_PRIVATE void MSG_mailbox_free(void *mailbox);
  43
  44 /* \brief MSG_mailbox_get_by_alias - get a mailbox from its alias.
  45  *
  46  * The function MSG_mailbox_get_by_alias returns the mailbox associated with
  47  * the key specified by the parameter alias. If the mailbox does not exists,
  48  * the function create it.
  49  *
  50  * \param alias    The alias of the mailbox to return.
  51  *
  52  * \return  The mailbox associated with the alias specified as parameter
  53  *    or a new mailbox if the key does not match.
  54  */
  55 XBT_PUBLIC(msg_mailbox_t)
  56     MSG_mailbox_get_by_alias(const char *alias);
  57
  58 /*! \brief MSG_mailbox_is_empty - test if a mailbox is empty.
  59  *
  60  * The function MSG_mailbox_is_empty tests if a mailbox is empty
  61  * (contains no msg task).
  62  *
  63  * \param mailbox  The mailbox to get test.
  64  *
  65  * \return  The function returns 1 if the mailbox is empty. Otherwise the function
  66  *    returns 0.
  67  */
  68 XBT_PUBLIC(int) MSG_mailbox_is_empty(msg_mailbox_t mailbox);
  69
  70 /* \brief MSG_mailbox_set_async - set a mailbox as eager
  71  *
  72  * The function MSG_mailbox_set_async sets the mailbox to a permanent receiver mode
  73  * Messages sent to this mailbox will then be sent just after the send is issued,
  74  * without waiting for the corresponding receive.
  75  *
  76  * This call should be done before issuing any receive, and on the receiver's side only
  77  *
  78  * \param alias    The alias of the mailbox to modify.
  79  *
  80  */
  81 XBT_PUBLIC(void) MSG_mailbox_set_async(const char *alias);
  82
  83 /*! \brief MSG_mailbox_get_head - get the task at the head of a mailbox.
  84  *
  85  * The MSG_mailbox_get_head returns the task at the head of the mailbox.
  86  * This function does not remove the task from the mailbox (contrary to
  87  * the function MSG_mailbox_pop_head).
  88  *
  89  * \param mailbox  The mailbox concerned by the operation.
  90  *
  91  * \return    The task at the head of the mailbox.
  92  */
  93 XBT_PUBLIC(msg_task_t)
  94     MSG_mailbox_get_head(msg_mailbox_t mailbox);
  95
  96 /*! \brief MSG_mailbox_get_count_host_waiting_tasks - Return the number of tasks
  97    waiting to be received in a mailbox and sent by a host.
  98  *
  99  * \param mailbox  The mailbox concerned by the operation.
 100  * \param host    The msg host containing the processes that have sended the
 101  *      tasks.
 102  *
 103  * \return    The number of tasks in the mailbox specified by the
 104  *      parameter mailbox and sended by all the processes located
 105  *      on the host specified by the parameter host.
 106  */
 107 XBT_PUBLIC(int)
 108 MSG_mailbox_get_count_host_waiting_tasks(msg_mailbox_t mailbox,
 109                                          msg_host_t host);
 110
 111 SG_END_DECL()
 112 #endif                          /* !MSG_MAILBOX_H */