1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
Receives a message from the queue.
copyrights:
- Copyright (C) 2021 embedded brains GmbH & Co. KG
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default:
attributes: null
body: null
params:
- ${../../type/if/id:/name} ${.:/params[0]/name}
- void *${.:/params[1]/name}
- ${/c/if/size_t:/name} *${.:/params[2]/name}
- ${../../option/if/option:/name} ${.:/params[3]/name}
- ${../../type/if/interval:/name} ${.:/params[4]/name}
return: ${../../status/if/code:/name}
variants: []
description: |
This directive receives a message from the queue specified by
${.:/params[0]/name}.
The **option set** specified in ${.:/params[3]/name} is built through a
*bitwise or* of the option constants described below. Not all combinations
of options are allowed. Some options are mutually exclusive. If mutually
exclusive options are combined, the behaviour is undefined. Options not
mentioned below are not evaluated by this directive and have no effect.
Default options can be selected by using the ${../../option/if/default:/name}
constant.
The calling task can **wait** or **try to receive** a message from the queue
according to the mutually exclusive ${../../option/if/wait:/name} and
${../../option/if/no-wait:/name} options.
* **Waiting to receive** a message from the queue is the default and can be
emphasized through the use of the ${../../option/if/wait:/name} option.
The ${.:/params[4]/name} parameter defines how long the calling task is
willing to wait. Use ${../../type/if/no-timeout:/name} to wait potentially
forever, otherwise set a timeout interval in clock ticks.
* **Trying to receive** a message from the queue is selected by the
${../../option/if/no-wait:/name} option. If this option is defined, then
the ${.:/params[4]/name} parameter is ignored. When a message from the
queue cannot be immediately received, then the
${../../status/if/unsatisfied:/name} status is returned.
With either ${../../option/if/wait:/name} or ${../../option/if/no-wait:/name}
if there is at least one message in the queue, then it is copied to the
buffer, the size is set to return the length of the message in bytes, and
this directive returns immediately with the
${../../status/if/successful:/name} status code. The buffer has to be big
enough to receive a message of the maximum length with respect to this
message queue.
If the calling task chooses to return immediately and the queue is empty,
then the directive returns immediately with the
${../../status/if/unsatisfied:/name} status code. If the calling task
chooses to wait at the message queue and the queue is empty, then the calling
task is placed on the message wait queue and blocked. If the queue was
created with the ${../../attr/if/priority:/name} option specified, then the
calling task is inserted into the wait queue according to its priority. But,
if the queue was created with the ${../../attr/if/fifo:/name} option
specified, then the calling task is placed at the rear of the wait queue.
enabled-by: true
index-entries:
- receive message from a queue
interface-type: function
links:
- role: interface-placement
uid: header
- role: interface-ingroup
uid: group
- role: constraint
uid: ../constraint/receive-isr
- role: constraint
uid: /constraint/directive-ctx-task
- role: constraint
uid: ../../constraint/request-may-block
- role: constraint
uid: /constraint/clock-tick
- role: constraint
uid: /constraint/directive-remote
name: rtems_message_queue_receive
notes: null
params:
- description: |
is the queue identifier.
dir: null
name: id
- description: |
is the begin address of the buffer to receive the message. The buffer
shall be large enough to receive a message of the maximum length of the
queue as defined by ${create:/name} or ${construct:/name}. The
${.:/params[2]/name} parameter cannot be used to specify the size of the
buffer.
dir: null
name: buffer
- description: |
is the pointer to a ${/c/if/size_t:/name} object. When the directive call
is successful, the size in bytes of the received messages will be stored in
this object. This parameter cannot be used to specify the size of the
buffer.
dir: out
name: size
- description: |
is the option set.
dir: null
name: option_set
- description: |
is the timeout in ${/glossary/clock-tick:/plural} if the
${../../option/if/wait:/name} option is set. Use
${../../type/if/no-timeout:/name} to wait potentially forever.
dir: null
name: timeout
return:
return: null
return-values:
- description: |
The requested operation was successful.
value: ${../../status/if/successful:/name}
- description: |
There was no queue associated with the identifier specified by
${.:/params[0]/name}.
value: ${../../status/if/invalid-id:/name}
- description: |
The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
value: ${../../status/if/invalid-address:/name}
- description: |
The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
value: ${../../status/if/invalid-address:/name}
- description: |
The queue was empty.
value: ${../../status/if/unsatisfied:/name}
- description: |
The timeout happened while the calling task was waiting to receive a
message
value: ${../../status/if/timeout:/name}
- description: |
The queue was deleted while the calling task was waiting to receive a
message.
value: ${../../status/if/object-was-deleted:/name}
type: interface
|
