message.h

   1 #ifndef _message__h__included__
   2 #define _message__h__included__
   3
   4 struct object;
   5
   6 /* Message. */
   7 struct message;
   8
   9 /* Message queue. */
  10 struct message_queue;
  11
  12 /******************************************************************************
  13  *
  14  * DESCRIPTION:
  15  *      Create message queue.
  16  *
  17  * RETURN VALUE:
  18  *      Message queue.
  19  *
  20  *****************************************************************************/
  21 struct message_queue* message_queue_create();
  22
  23 /******************************************************************************
  24  *
  25  * DESCRIPTION:
  26  *      Destroy message queue and all messages in it.
  27  *
  28  * PARAMETERS:
  29  *      queue                   The message queue to destroy.
  30  *
  31  *****************************************************************************/
  32 void message_queue_destroy(struct message_queue* queue);
  33
  34 /******************************************************************************
  35  *
  36  * DESCRIPTION:
  37  *      Add message to queue.
  38  *
  39  * PARAMETERS:
  40  *      queue                   The message queue to add message to.
  41  *      msg                     The message to add.
  42  *
  43  *****************************************************************************/
  44 void message_queue_queue(struct message_queue* queue, struct message* msg);
  45
  46 /******************************************************************************
  47  *
  48  * DESCRIPTION:
  49  *      Deque message from queue. Only messages destined to objects with
  50  *      executing flag clear are considered.
  51  *
  52  * PARAMETERS:
  53  *      queue                   The message queue to deque from
  54  *
  55  * RETURN VALUE:
  56  *      The dequed message, or NULL if no suitable message exists.
  57  *
  58  *****************************************************************************/
  59 struct message* message_queue_deque(struct message_queue* queue);
  60
  61 /******************************************************************************
  62  *
  63  * DESCRIPTION:
  64  *      Call callback for all messages in queue.
  65  *
  66  * PARAMETERS:
  67  *      queue                   The message queue to handle.
  68  *      callback                The callback to call.
  69  *
  70  *****************************************************************************/
  71 void message_queue_forall(struct message_queue* queue,
  72         void (*callback)(struct message* msg));
  73
  74 /******************************************************************************
  75  *
  76  * DESCRIPTION:
  77  *      Get message target.
  78  *
  79  * PARAMETERS:
  80  *      msg                     The message.
  81  *
  82  * RETURN VALUE:
  83  *      Message target object.
  84  *
  85  *****************************************************************************/
  86 struct object* message_target(struct message* msg);
  87
  88 /******************************************************************************
  89  *
  90  * DESCRIPTION:
  91  *      Get number of parameters in message.
  92  *
  93  * PARAMETERS:
  94  *      msg                     The message.
  95  *
  96  * RETURN VALUE:
  97  *      Number of parameters.
  98  *
  99  *****************************************************************************/
 100 size_t message_parameters(struct message* msg);
 101
 102 /******************************************************************************
 103  *
 104  * DESCRIPTION:
 105  *      Read slot value. Reading undefined slot gives NULL.
 106  *
 107  * PARAMETERS:
 108  *      msg                     The message.
 109  *      slot                    Slot nubmer.
 110  *
 111  * RETURN VALUE:
 112  *      Reference in slot.
 113  *
 114  *****************************************************************************/
 115 struct object* message_read_slot(struct message* msg, size_t slot);
 116
 117 /******************************************************************************
 118  *
 119  * DESCRIPTION:
 120  *      Write slot value. Writing undefined slot is no-operation.
 121  *
 122  * PARAMETERS:
 123  *      msg                     The message.
 124  *      slot                    Slot nubmer.
 125  *      obj                     Object to write.
 126  *
 127  *****************************************************************************/
 128 void message_write_slot(struct message* msg, size_t slot, struct object* obj);
 129
 130 /******************************************************************************
 131  *
 132  * DESCRIPTION:
 133  *      Create new message.
 134  *
 135  * PARAMETERS:
 136  *      target                  Target of message.
 137  *      parameters              Number of parameters.
 138  *
 139  * RETURN VALUE:
 140  *      Constructed message. Free with free.
 141  *
 142  *****************************************************************************/
 143 struct message* message_create(struct object* target, size_t parameters);
 144
 145 #endif