EM-ODP  3.7.0
Event Machine on ODP
event_machine_scheduler.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015, Nokia Solutions and Networks
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * * Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  * * Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the distribution.
14  * * Neither the name of the copyright holder nor the names of its
15  * contributors may be used to endorse or promote products derived
16  * from this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 
31 #ifndef EVENT_MACHINE_SCHEDULER_H_
32 #define EVENT_MACHINE_SCHEDULER_H_
33 
34 #pragma GCC visibility push(default)
35 
36 /**
37  * @file
38  * @defgroup em_scheduler Scheduler
39  * Event Machine event scheduling related services
40  * @{
41  *
42  * Most of the event scheduling is a system dependent implementation but the
43  * common services here can be used for performance tuning etc.
44  *
45  * Do not include this from the application, event_machine.h will
46  * do it for you.
47  */
48 
49 #ifdef __cplusplus
50 extern "C" {
51 #endif
52 
53 /**
54  * A hint to release an atomic processing context.
55  *
56  * This function can be used to release the atomic context before returning from
57  * the EO receive function.
58  *
59  * After this API call is the scheduler allowed to schedule another event from
60  * the same atomic queue (or atomic group) that established the current
61  * atomic context, to another (or same) core.
62  *
63  * When an event has been received from an atomic queue, the scheduler is
64  * allowed to schedule another event from the same atomic queue to another,
65  * or same, core after this API call. This increases parallelism and may improve
66  * performance - however, the exclusive processing and ordering might be lost.
67  * Note, however, that this is a hint only, the scheduler is still allowed to
68  * keep the atomic context until scheduling the next event.
69  *
70  * Can only be called from within the EO receive function.
71  *
72  * The call is ignored if the currently active scheduling context type is not
73  * atomic (EM_SCHED_CONTEXT_TYPE_ATOMIC, see em_sched_context_type_current()).
74  *
75  * Pseudo-code example:
76  * @code
77  * receive_func(void* eo_ctx, em_event_t event, em_event_type_t type,
78  * em_queue_t queue, void* q_ctx)
79  * {
80  * if(is_my_atomic_queue(q_ctx))
81  * {
82  * // this needs to be done atomically:
83  * update_sequence_number(event);
84  *
85  * em_atomic_processing_end();
86  * // do other processing (potentially) in parallel:
87  * do_long_parallel_work();
88  * }
89  * }
90  * @endcode
91  *
92  * @see em_receive_func_t(), event_machine_queue.h
93  */
94 void em_atomic_processing_end(void);
95 
96 /**
97  * A hint to allow release of the ordered processing context.
98  *
99  * This function can be used to tell the scheduler that all events to be sent
100  * under the current ordering context are already sent. Events sent after this
101  * are no longer required to be kept in order. This may increase system
102  * performance. It permits early release of the ordering context, but an
103  * EM implementation is still allowed to keep it until scheduling the next
104  * incoming event.
105  *
106  * Can only be called from within the EO receive function.
107  *
108  * The call is ignored if the currently active scheduling context type is not
109  * ordered (EM_SCHED_CONTEXT_TYPE_ORDERED, see em_sched_context_type_current()).
110  *
111  * The ordering context cannot be resumed after it has been released.
112  *
113  * @see em_receive_func_t(), event_machine_queue.h
114  */
115 void em_ordered_processing_end(void);
116 
117 /**
118  * A hint to start scheduling for this core
119  *
120  * This is a performance optimization hint with no functional effect. A hint is
121  * given to the scheduler to start scheduling the next event for the calling
122  * core as it is about to end processing of the current event. This can be used
123  * to reduce the latency of scheduling.
124  * Depending on the actual scheduler implementation, this may be a no-operation.
125  */
126 void em_preschedule(void);
127 
128 /**
129  * Return the currently active scheduling context type
130  *
131  * Returns the current scheduling context type (none, ordered, atomic) and
132  * optionally the queue that determines the context.
133  * Note, that the scheduling context type is not the same as the queue type
134  * since the scheduling context type could have been released by the user, or
135  * inherited by local queue processing.
136  *
137  * This function is mainly for handling local queues that inherit the scheduling
138  * context that was active for the sending EO. The scheduling context can be
139  * unpredictable unless the processing chain is carefully crafted.
140  * This function will return the active scheduling context type and queue of the
141  * last event from the scheduler (i.e. the scheduled queue of the EO that sent
142  * the event to the first local queue in the chain).
143  *
144  * @param[out] queue if not NULL, set to the queue that determines the current
145  * sched context
146  *
147  * @return current context type
148  *
149  * @see em_queue_create(), em_sched_context_type_t
150  */
152 em_sched_context_type_current(em_queue_t *queue);
153 
154 /**
155  * @}
156  */
157 #ifdef __cplusplus
158 }
159 #endif
160 
161 #pragma GCC visibility pop
162 #endif /* EVENT_MACHINE_SCHEDULER_H_ */
em_ordered_processing_end
void em_ordered_processing_end(void)
Definition: event_machine_scheduler.c:60
em_atomic_processing_end
void em_atomic_processing_end(void)
Definition: event_machine_scheduler.c:34
em_preschedule
void em_preschedule(void)
Definition: event_machine_scheduler.c:83
em_sched_context_type_current
em_sched_context_type_t em_sched_context_type_current(em_queue_t *queue)
Definition: event_machine_scheduler.c:89
em_sched_context_type_t
em_sched_context_type_t
Definition: event_machine_types.h:277