source: rtems/cpukit/score/include/rtems/score/coremsg.h @ 53fb837a

4.104.114.84.95
Last change on this file since 53fb837a was 53fb837a, checked in by Joel Sherrill <joel.sherrill@…>, on 01/13/00 at 19:25:15

POSIX message queues now include complete functionality including
blocking sends when the queue is full. The SuperCore? was enhanced
to support blocking on send. The existing POSIX API was debugged
and numerous test cases were added to psxmsgq01 by Jennifer Averett.
SuperCore? enhancements and resulting modifications to other APIs
were done by Joel.

There is one significant point of interpretation for the POSIX API.
What happens to threads already blocked on a message queue when the
mode of that same message queue is changed from blocking to non-blocking?
We decided to unblock all waiting tasks with an EAGAIN error just
as if a non-blocking version of the same operation had returned
unsatisfied. This case is not discussed in the POSIX standard and
other implementations may have chosen differently.

  • Property mode set to 100644
File size: 8.2 KB
Line 
1/*  coremsg.h
2 *
3 *  This include file contains all the constants and structures associated
4 *  with the Message queue Handler.
5 *
6 *  COPYRIGHT (c) 1989-1999.
7 *  On-Line Applications Research Corporation (OAR).
8 *
9 *  The license and distribution terms for this file may be
10 *  found in the file LICENSE in this distribution or at
11 *  http://www.OARcorp.com/rtems/license.html.
12 *
13 *  $Id$
14 */
15 
16#ifndef __RTEMS_CORE_MESSAGE_QUEUE_h
17#define __RTEMS_CORE_MESSAGE_QUEUE_h
18 
19#ifdef __cplusplus
20extern "C" {
21#endif
22
23#include <limits.h>
24#include <rtems/score/thread.h>
25#include <rtems/score/threadq.h>
26#include <rtems/score/priority.h>
27#include <rtems/score/watchdog.h>
28 
29/*
30 *  The following type defines the callout which the API provides
31 *  to support global/multiprocessor operations on message_queues.
32 */
33 
34typedef void ( *CORE_message_queue_API_mp_support_callout )(
35                 Thread_Control *,
36                 Objects_Id
37             );
38
39/*
40 *  The following defines the data types needed to manipulate
41 *  the contents of message buffers.
42 *
43 *  NOTE:  The buffer field is normally longer than a single unsigned32.
44 *         but since messages are variable length we just make a ptr to 1. 
45 */
46 
47typedef struct {
48    unsigned32  size;
49    unsigned32  buffer[1];
50} CORE_message_queue_Buffer;
51 
52/*
53 *  The following records define the organization of a message
54 *  buffer.
55 */
56 
57typedef struct {
58  Chain_Node                 Node;
59  int                        priority;
60  CORE_message_queue_Buffer  Contents;
61}   CORE_message_queue_Buffer_control;
62
63/*
64 *  Blocking disciplines for a message_queue.
65 */
66
67typedef enum {
68  CORE_MESSAGE_QUEUE_DISCIPLINES_FIFO,
69  CORE_MESSAGE_QUEUE_DISCIPLINES_PRIORITY
70}   CORE_message_queue_Disciplines;
71
72/*
73 *  The following enumerated type details the modes in which a message
74 *  may be submitted to a message queue.  The message may be posted
75 *  in a send or urgent fashion.
76 *
77 *  NOTE:  All other values are message priorities.  Numerically smaller
78 *         priorities indicate higher priority messages.
79 *
80 */
81
82#define  CORE_MESSAGE_QUEUE_SEND_REQUEST   INT_MAX
83#define  CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN
84 
85typedef int CORE_message_queue_Submit_types;
86
87/*
88 *  Core Message queue handler return statuses.
89 */
90 
91typedef enum {
92  CORE_MESSAGE_QUEUE_STATUS_SUCCESSFUL,
93  CORE_MESSAGE_QUEUE_STATUS_INVALID_SIZE,
94  CORE_MESSAGE_QUEUE_STATUS_TOO_MANY,
95  CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED,
96  CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_NOWAIT,
97  CORE_MESSAGE_QUEUE_STATUS_WAS_DELETED,
98  CORE_MESSAGE_QUEUE_STATUS_TIMEOUT
99}   CORE_message_queue_Status;
100
101/*
102 *  The following defines the control block used to manage the
103 *  attributes of each message queue.
104 */
105
106typedef struct {
107  CORE_message_queue_Disciplines  discipline;
108}   CORE_message_queue_Attributes;
109 
110/*
111 *  The following defines the type for a Notification handler.  A notification
112 *  handler is invoked when the message queue makes a 0->1 transition on
113 *  pending messages.
114 */
115
116typedef void (*CORE_message_queue_Notify_Handler)( void * );
117
118/*
119 *  The following defines the control block used to manage each
120 *  counting message_queue.
121 */
122 
123typedef struct {
124  Thread_queue_Control               Wait_queue;
125  CORE_message_queue_Attributes      Attributes;
126  unsigned32                         maximum_pending_messages;
127  unsigned32                         number_of_pending_messages;
128  unsigned32                         maximum_message_size;
129  Chain_Control                      Pending_messages;
130  CORE_message_queue_Buffer         *message_buffers;
131  CORE_message_queue_Notify_Handler  notify_handler;
132  void                              *notify_argument;
133  Chain_Control                      Inactive_messages;
134}   CORE_message_queue_Control;
135
136/*
137 *  _CORE_message_queue_Initialize
138 *
139 *  DESCRIPTION:
140 *
141 *  This routine initializes the message_queue based on the parameters passed.
142 */
143
144boolean _CORE_message_queue_Initialize(
145  CORE_message_queue_Control    *the_message_queue,
146  Objects_Classes                the_class,
147  CORE_message_queue_Attributes *the_message_queue_attributes,
148  unsigned32                     maximum_pending_messages,
149  unsigned32                     maximum_message_size,
150  Thread_queue_Extract_callout   proxy_extract_callout
151);
152 
153/*
154 *  _CORE_message_queue_Close
155 *
156 *  DESCRIPTION:
157 *
158 *  This function closes a message by returning all allocated space and
159 *  flushing the message_queue's task wait queue.
160 */
161 
162void _CORE_message_queue_Close(
163  CORE_message_queue_Control *the_message_queue,
164  Thread_queue_Flush_callout  remote_extract_callout,
165  unsigned32                  status
166);
167
168/*
169 *  _CORE_message_queue_Flush
170 *
171 *  DESCRIPTION:
172 *
173 *  This function flushes the message_queue's pending message queue.  The
174 *  number of messages flushed from the queue is returned.
175 *
176 */
177
178unsigned32 _CORE_message_queue_Flush(
179  CORE_message_queue_Control *the_message_queue
180);
181
182/*
183 *  _CORE_message_queue_Flush_support
184 *
185 *  DESCRIPTION:
186 *
187 *  This routine flushes all outstanding messages and returns
188 *  them to the inactive message chain.
189 */
190 
191unsigned32 _CORE_message_queue_Flush_support(
192  CORE_message_queue_Control *the_message_queue
193);
194 
195/*
196 *  _CORE_message_queue_Flush_waiting_threads
197 *
198 *  DESCRIPTION:
199 *
200 *  This function flushes the threads which are blocked on this
201 *  message_queue's pending message queue.  They are unblocked whether
202 *  blocked sending or receiving.
203 */
204
205void _CORE_message_queue_Flush_waiting_threads(
206  CORE_message_queue_Control *the_message_queue
207);
208
209/*
210 *  _CORE_message_queue_Broadcast
211 *
212 *  DESCRIPTION:
213 *
214 *  This function sends a message for every thread waiting on the queue and
215 *  returns the number of threads made ready by the message.
216 *
217 */
218 
219CORE_message_queue_Status _CORE_message_queue_Broadcast(
220  CORE_message_queue_Control                *the_message_queue,
221  void                                      *buffer,
222  unsigned32                                 size,
223  Objects_Id                                 id,
224  CORE_message_queue_API_mp_support_callout  api_message_queue_mp_support,
225  unsigned32                                *count
226);
227
228/*
229 *  _CORE_message_queue_Submit
230 *
231 *  DESCRIPTION:
232 *
233 *  This routine implements the send and urgent message functions. It
234 *  processes a message that is to be submitted to the designated
235 *  message queue.  The message will either be processed as a
236 *  send message which it will be inserted at the rear of the queue
237 *  or it will be processed as an urgent message which will be inserted
238 *  at the front of the queue.
239 *
240 */
241 
242void _CORE_message_queue_Submit(
243  CORE_message_queue_Control                *the_message_queue,
244  void                                      *buffer,
245  unsigned32                                 size,
246  Objects_Id                                 id,
247  CORE_message_queue_API_mp_support_callout  api_message_queue_mp_support,
248  CORE_message_queue_Submit_types            submit_type,
249  boolean                                    wait,
250  Watchdog_Interval                          timeout
251);
252
253/*
254 *  _CORE_message_queue_Seize
255 *
256 *  DESCRIPTION:
257 *
258 *  This kernel routine dequeues a message, copies the message buffer to
259 *  a given destination buffer, and frees the message buffer to the
260 *  inactive message pool.  The thread will be blocked if wait is TRUE,
261 *  otherwise an error will be given to the thread if no messages are available.
262 *
263 *  NOTE: Returns message priority via return are in TCB.
264 */
265 
266void _CORE_message_queue_Seize(
267  CORE_message_queue_Control      *the_message_queue,
268  Objects_Id                       id,
269  void                            *buffer,
270  unsigned32                      *size,
271  boolean                          wait,
272  Watchdog_Interval                timeout
273);
274
275/*
276 *  _CORE_message_queue_Insert_message
277 *
278 *  DESCRIPTION:
279 *
280 *  This kernel routine inserts the specified message into the
281 *  message queue.  It is assumed that the message has been filled
282 *  in before this routine is called.
283 */
284
285void _CORE_message_queue_Insert_message(
286  CORE_message_queue_Control        *the_message_queue,
287  CORE_message_queue_Buffer_control *the_message,
288  CORE_message_queue_Submit_types    submit_type
289);
290
291#ifndef __RTEMS_APPLICATION__
292#include <rtems/score/coremsg.inl>
293#endif
294
295#ifdef __cplusplus
296}
297#endif
298 
299#endif
300/*  end of include file */
301
Note: See TracBrowser for help on using the repository browser.