src/msg/mailbox.h

   1 /* Copyright (c) 2008, 2009, 2010. 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 SMX_MAILBOX_H
   8 #define SMX_MAILBOX_H
   9
  10 #include "xbt/fifo.h"
  11 #include "simix/simix.h"
  12 #include "msg/datatypes.h"
  13
  14
  15 SG_BEGIN_DECL()
  16 #define MAX_ALIAS_NAME  ((size_t)260)
  17 /*
  18  * Initialization of the mailbox module.
  19  */
  20      void MSG_mailbox_mod_init(void);
  21
  22 /*
  23  * Terminaison of the mailbox module.
  24  */
  25      void MSG_mailbox_mod_exit(void);
  26
  27
  28 /*! \brief MSG_mailbox_new - create a new mailbox.
  29  *
  30  * The function MSG_mailbox_new creates a new mailbox identified by the key specified
  31  * by the parameter alias and add it in the global dictionary.
  32  *
  33  * \param alias         The alias of the mailbox to create.
  34  *
  35  * \return              The newly created mailbox.
  36  */
  37 XBT_PUBLIC(msg_mailbox_t)
  38   MSG_mailbox_new(const char *alias);
  39
  40 /*! \brief MSG_mailbox_create - create a new mailbox.
  41  *
  42  * The function MSG_mailbox_new creates a new mailbox identified by
  43  * the key specified by the parameter alias and add it in the global
  44  * dictionary but doesn't add it in the global dictionary. Typicaly,
  45  * this type of mailbox is associated with a channel.
  46  *
  47  * \param alias         The alias of the mailbox to create.
  48  *
  49  * \return              The newly created mailbox.
  50  */
  51      msg_mailbox_t MSG_mailbox_create(const char *alias);
  52
  53 /* \brief MSG_mailbox_free - release a mailbox from the memory.
  54  *
  55  * The function MSG_mailbox_free release a mailbox from the memory but does
  56  * not remove it from the dictionary.
  57  *
  58  * \param mailbox       The mailbox to release.
  59  *
  60  * \see                 MSG_mailbox_destroy.
  61  */
  62      void MSG_mailbox_free(void *mailbox);
  63
  64 /* \brief MSG_mailbox_get_by_alias - get a mailbox from its alias.
  65  *
  66  * The function MSG_mailbox_get_by_alias returns the mailbox associated with
  67  * the key specified by the parameter alias. If the mailbox does not exists,
  68  * the function create it.
  69  *
  70  * \param alias         The alias of the mailbox to return.
  71  *
  72  * \return      The mailbox associated with the alias specified as parameter
  73  *              or a new mailbox if the key does not match.
  74  */
  75 XBT_PUBLIC(msg_mailbox_t)
  76   MSG_mailbox_get_by_alias(const char *alias);
  77
  78 /* \brief MSG_mailbox_get_by_channel - get a mailbox of the specified host from its channel.
  79  *
  80  * The function MSG_mailbox_get_by_channel returns the mailbox of the
  81  * specified host from the channel specified by the parameter
  82  * channel. If the mailbox does not exists, the function fails.
  83  *
  84  * \param host          The host containing he mailbox to get.
  85  * \param channel       The channel used to identify the mailbox.
  86  *
  87  * \return The mailbox of the specified host associated the channel
  88  *         specified as parameter.
  89  *
  90  */
  91 XBT_PUBLIC(msg_mailbox_t)
  92   MSG_mailbox_get_by_channel(m_host_t host, m_channel_t channel);
  93
  94 /*! \brief MSG_mailbox_get_alias - get the alias associated with the mailbox.
  95  *
  96  * The function MSG_mailbox_get_alias returns the alias of the mailbox specified
  97  * by the parameter mailbox.
  98  *
  99  * \param mailbox       The mailbox to get the alias.
 100  *
 101  * \return      The alias of the mailbox specified by the parameter mailbox.
 102  */
 103 XBT_PUBLIC(const char *) MSG_mailbox_get_alias(msg_mailbox_t mailbox);
 104
 105 /*! \brief MSG_mailbox_get_cond - get the simix condition of a mailbox.
 106  *
 107  * The function MSG_mailbox_get_cond returns the condition of the
 108  * mailbox specified by the parameter mailbox.
 109  *
 110  * \param mailbox       The mailbox to get the condition.
 111  *
 112  * \return The simix condition of the mailbox specified by the parameter mailbox.
 113  */
 114 XBT_PUBLIC(smx_cond_t)
 115   MSG_mailbox_get_cond(msg_mailbox_t mailbox);
 116
 117 /*! \brief MSG_mailbox_set_cond - set the simix condition of a mailbox.
 118  *
 119  * The function MSG_mailbox_set_cond set the condition of the mailbox
 120  * specified by the parameter mailbox.
 121  *
 122  * \param mailbox       The mailbox to set the condition.
 123  * \param cond          The new simix condition of the mailbox.
 124  *
 125  */
 126 XBT_PUBLIC(void) MSG_mailbox_set_cond(msg_mailbox_t mailbox, smx_cond_t cond);
 127
 128 /*! \brief MSG_mailbox_is_empty - test if a mailbox is empty.
 129  *
 130  * The function MSG_mailbox_is_empty tests if a mailbox is empty
 131  * (contains no msg task).
 132  *
 133  * \param mailbox       The mailbox to get test.
 134  *
 135  * \return      The function returns 1 if the mailbox is empty. Otherwise the function
 136  *              returns 0.
 137  */
 138 XBT_PUBLIC(int) MSG_mailbox_is_empty(msg_mailbox_t mailbox);
 139
 140 /*! \brief MSG_mailbox_get_head - get the task at the head of a mailbox.
 141  *
 142  * The MSG_mailbox_get_head returns the task at the head of the mailbox.
 143  * This function does not remove the task from the mailbox (contrary to
 144  * the function MSG_mailbox_pop_head).
 145  *
 146  * \param mailbox       The mailbox concerned by the operation.
 147  *
 148  * \return              The task at the head of the mailbox.
 149  */
 150 XBT_PUBLIC(m_task_t)
 151   MSG_mailbox_get_head(msg_mailbox_t mailbox);
 152
 153 /*! \brief MSG_mailbox_get_count_host_waiting_tasks - Return the number of tasks
 154    waiting to be received in a mailbox and sent by a host.
 155  *
 156  * \param mailbox       The mailbox concerned by the operation.
 157  * \param host          The msg host containing the processes that have sended the
 158  *                      tasks.
 159  *
 160  * \return              The number of tasks in the mailbox specified by the
 161  *                      parameter mailbox and sended by all the processes located
 162  *                      on the host specified by the parameter host.
 163  */
 164 XBT_PUBLIC(int)
 165 MSG_mailbox_get_count_host_waiting_tasks(msg_mailbox_t mailbox,
 166                                          m_host_t host);
 167
 168
 169 SG_END_DECL()
 170 #endif /* !SMX_MAILBOX_H */