1 | SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause |
---|
2 | brief: | |
---|
3 | Receives or gets an event set from the calling task. |
---|
4 | copyrights: |
---|
5 | - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) |
---|
6 | - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) |
---|
7 | definition: |
---|
8 | default: |
---|
9 | attributes: null |
---|
10 | body: null |
---|
11 | params: |
---|
12 | - ${set:/name} ${.:/params[0]/name} |
---|
13 | - ${../../option/if/option:/name} ${.:/params[1]/name} |
---|
14 | - ${../../type/if/interval:/name} ${.:/params[2]/name} |
---|
15 | - ${set:/name} *${.:/params[3]/name} |
---|
16 | return: ${../../status/if/code:/name} |
---|
17 | variants: [] |
---|
18 | description: | |
---|
19 | This directive can be used to |
---|
20 | |
---|
21 | * get the pending events of the calling task, or |
---|
22 | |
---|
23 | * receive events. |
---|
24 | |
---|
25 | To **get the pending events** use the constant ${pending-events:/name} for |
---|
26 | the ``${.:/params[0]/name}`` parameter. The pending events are returned to |
---|
27 | the calling task but the event set of the task is left unaltered. The |
---|
28 | ``${.:/params[1]/name}`` and ``${.:params[2]/name}`` parameters are ignored |
---|
29 | in this case. The directive returns immediately and does not block. |
---|
30 | |
---|
31 | To **receive events** you have to define an input event condition and some |
---|
32 | options. The **option set** specified in ``${.:/params[1]/name}`` defines |
---|
33 | |
---|
34 | * if the task will wait or poll for the events, and |
---|
35 | |
---|
36 | * if the task wants to receive all or any of the input events. |
---|
37 | |
---|
38 | The option set is built through a *bitwise or* of the option constants |
---|
39 | described below. |
---|
40 | |
---|
41 | The task can **wait** or **poll** for the events. |
---|
42 | |
---|
43 | * **Waiting** for events is the default and can be emphasized through the use |
---|
44 | of the ${../../option/if/wait:/name} option. The ``${.:/params[2]/name}`` |
---|
45 | parameter defines how long the task is willing to wait. Use |
---|
46 | ${../../type/if/no-timeout:/name} to wait potentially forever, otherwise |
---|
47 | set a timeout interval in clock ticks. |
---|
48 | |
---|
49 | * Not waiting for events (**polling**) is selected by the |
---|
50 | ${../../option/if/no-wait:/name} option. If this option is defined, then |
---|
51 | the ``${.:/params[2]/name}`` parameter is ignored. |
---|
52 | |
---|
53 | The task can receive **all** or **any** of the input events specified in |
---|
54 | ``${.:/params[0]/name}``. |
---|
55 | |
---|
56 | * Receiving **all** input events is the default and can be emphasized through |
---|
57 | the use of the ${../../option/if/event-all:/name} option. |
---|
58 | |
---|
59 | * Receiving **any** of the input events is selected by the |
---|
60 | ${../../option/if/event-any:/name} option. |
---|
61 | enabled-by: true |
---|
62 | index-entries: [] |
---|
63 | interface-type: function |
---|
64 | links: |
---|
65 | - role: interface-placement |
---|
66 | uid: header |
---|
67 | - role: interface-ingroup |
---|
68 | uid: group |
---|
69 | name: rtems_event_receive |
---|
70 | notes: | |
---|
71 | This directive shall be called by a task. Calling this directive from |
---|
72 | interrupt context is undefined behaviour. |
---|
73 | |
---|
74 | This directive only affects the events specified in ``${.:/params[0]/name}``. |
---|
75 | Any pending events that do not correspond to any of the events specified in |
---|
76 | ``${.:/params[0]/name}`` will be left pending. |
---|
77 | |
---|
78 | To receive all events use the event set constant ${all-events:/name} for the |
---|
79 | ``${.:/params[0]/name}`` parameter. Do not confuse this event set constant |
---|
80 | with the directive option ${../../option/if/event-all:/name}. |
---|
81 | |
---|
82 | A task can **receive all of the pending events** by calling the directive |
---|
83 | with a value of ${all-events:/name} for the ``${.:/params[0]/name}`` |
---|
84 | parameter and the bitwise or of the ${../../option/if/no-wait:/name} and |
---|
85 | ${../../option/if/event-any:/name} options for the ``${.:/params[1]/name}`` |
---|
86 | parameter. The pending events are returned and the event set of the task is |
---|
87 | cleared. If no events are pending then the |
---|
88 | ${../../status/if/unsatisfied:/name} status code will be returned. |
---|
89 | params: |
---|
90 | - description: | |
---|
91 | is the event set of interest. Use ${pending-events:/name} to get the |
---|
92 | pending events. |
---|
93 | dir: null |
---|
94 | name: event_in |
---|
95 | - description: is the option set. |
---|
96 | dir: null |
---|
97 | name: option_set |
---|
98 | - description: | |
---|
99 | is the timeout in clock ticks if the ${../../option/if/wait:/name} option |
---|
100 | is set. Use ${../../type/if/no-timeout:/name} to wait potentially |
---|
101 | forever. |
---|
102 | dir: null |
---|
103 | name: ticks |
---|
104 | - description: | |
---|
105 | is the pointer to an event set. The received or pending events are stored |
---|
106 | in the referenced event set if the operation was successful. |
---|
107 | dir: null |
---|
108 | name: event_out |
---|
109 | return: |
---|
110 | return: null |
---|
111 | return-values: |
---|
112 | - description: | |
---|
113 | The requested operation was successful. |
---|
114 | value: ${../../status/if/successful:/name} |
---|
115 | - description: | |
---|
116 | The ``${.:/params[3]/name}`` parameter was ${/c/if/null:/name}. |
---|
117 | value: ${../../status/if/invalid-address:/name} |
---|
118 | - description: | |
---|
119 | The events of interest were not immediately available. |
---|
120 | value: ${../../status/if/unsatisfied:/name} |
---|
121 | - description: | |
---|
122 | The events of interest were not available within the specified timeout |
---|
123 | interval. |
---|
124 | value: ${../../status/if/timeout:/name} |
---|
125 | type: interface |
---|