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 /*! \brief MSG_mailbox_new - create a new mailbox.
  19  *
  20  * The function MSG_mailbox_new creates a new mailbox identified by the key specified
  21  * by the parameter alias and add it in the global dictionary.
  22  *
  23  * \param alias         The alias of the mailbox to create.
  24  *
  25  * \return              The newly created mailbox.
  26  */
  27 XBT_PUBLIC(msg_mailbox_t)
  28     MSG_mailbox_new(const char *alias);
  29
  30 /*! \brief MSG_mailbox_create - create a new mailbox.
  31  *
  32  * The function MSG_mailbox_new creates a new mailbox identified by
  33  * the key specified by the parameter alias and add it in the global
  34  * dictionary but doesn't add it in the global dictionary. Typicaly,
  35  * this type of mailbox is associated with a channel.
  36  *
  37  * \param alias         The alias of the mailbox to create.
  38  *
  39  * \return              The newly created mailbox.
  40  */
  41 msg_mailbox_t MSG_mailbox_create(const char *alias);
  42
  43 /* \brief MSG_mailbox_free - release a mailbox from the memory.
  44  *
  45  * The function MSG_mailbox_free release a mailbox from the memory but does
  46  * not remove it from the dictionary.
  47  *
  48  * \param mailbox       The mailbox to release.
  49  *
  50  * \see                 MSG_mailbox_destroy.
  51  */
  52 void MSG_mailbox_free(void *mailbox);
  53
  54 /* \brief MSG_mailbox_get_by_alias - get a mailbox from its alias.
  55  *
  56  * The function MSG_mailbox_get_by_alias returns the mailbox associated with
  57  * the key specified by the parameter alias. If the mailbox does not exists,
  58  * the function create it.
  59  *
  60  * \param alias         The alias of the mailbox to return.
  61  *
  62  * \return      The mailbox associated with the alias specified as parameter
  63  *              or a new mailbox if the key does not match.
  64  */
  65 XBT_PUBLIC(msg_mailbox_t)
  66     MSG_mailbox_get_by_alias(const char *alias);
  67
  68 /* \brief MSG_mailbox_get_by_channel - get a mailbox of the specified host from its channel.
  69  *
  70  * The function MSG_mailbox_get_by_channel returns the mailbox of the
  71  * specified host from the channel specified by the parameter
  72  * channel. If the mailbox does not exists, the function fails.
  73  *
  74  * \param host          The host containing he mailbox to get.
  75  * \param channel       The channel used to identify the mailbox.
  76  *
  77  * \return The mailbox of the specified host associated the channel
  78  *         specified as parameter.
  79  *
  80  */
  81 XBT_PUBLIC(msg_mailbox_t)
  82     MSG_mailbox_get_by_channel(m_host_t host, m_channel_t channel);
  83
  84 /*! \brief MSG_mailbox_is_empty - test if a mailbox is empty.
  85  *
  86  * The function MSG_mailbox_is_empty tests if a mailbox is empty
  87  * (contains no msg task).
  88  *
  89  * \param mailbox       The mailbox to get test.
  90  *
  91  * \return      The function returns 1 if the mailbox is empty. Otherwise the function
  92  *              returns 0.
  93  */
  94 XBT_PUBLIC(int) MSG_mailbox_is_empty(msg_mailbox_t mailbox);
  95
  96 /*! \brief MSG_mailbox_get_head - get the task at the head of a mailbox.
  97  *
  98  * The MSG_mailbox_get_head returns the task at the head of the mailbox.
  99  * This function does not remove the task from the mailbox (contrary to
 100  * the function MSG_mailbox_pop_head).
 101  *
 102  * \param mailbox       The mailbox concerned by the operation.
 103  *
 104  * \return              The task at the head of the mailbox.
 105  */
 106 XBT_PUBLIC(m_task_t)
 107     MSG_mailbox_get_head(msg_mailbox_t mailbox);
 108
 109 /*! \brief MSG_mailbox_get_count_host_waiting_tasks - Return the number of tasks
 110    waiting to be received in a mailbox and sent by a host.
 111  *
 112  * \param mailbox       The mailbox concerned by the operation.
 113  * \param host          The msg host containing the processes that have sended the
 114  *                      tasks.
 115  *
 116  * \return              The number of tasks in the mailbox specified by the
 117  *                      parameter mailbox and sended by all the processes located
 118  *                      on the host specified by the parameter host.
 119  */
 120 XBT_PUBLIC(int)
 121 MSG_mailbox_get_count_host_waiting_tasks(msg_mailbox_t mailbox,
 122                                          m_host_t host);
 123
 124
 125 SG_END_DECL()
 126 #endif                          /* !SMX_MAILBOX_H */