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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
/*
* Copyright (c) 2017 Cisco and/or its affiliates.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @file rta_Framework.h
* @brief <#Brief Description#>
*
* rtaFramework executes inside the worker thread in callback from the event scheduler.
*
* It provides service functions to components and connectors so they do not need
* to be event aware.
*
* It also manages the command channel to communicate with rtaTransport in the API's thread.
*
* _Create(), _Start(), and _Destroy() are called from the API's thread. You should not
* call _Destroy until rtaFramework_GetStatus() is FRAMEWORK_SHUTDOWN.
*
* The framework can run in threaded mode or non-threaded mode. Including this one
* header gives you both sets of operations, but they are not compatible.
*
* THREADED MODE:
* call _Create
* call _Start
* ... do work ...
* call _Shutdown
* call _Destroy
*
* NON-THREADED MODE
* call _Create
* ... do work ...
* call _Step or _StepCount or _StepTimed
* ... do work ...
* call _Step or _StepCount or _StepTimed
* ... do work ...
* call _Teardown
* call _Destroy
*
*/
#ifndef Libccnx_rta_Framework_h
#define Libccnx_rta_Framework_h
#include <parc/concurrent/parc_RingBuffer_1x1.h>
#include <parc/concurrent/parc_Notifier.h>
#include <ccnx/transport/transport_rta/core/rta_Logger.h>
// ===================================
// External API, used by rtaTransport
struct rta_framework;
typedef struct rta_framework RtaFramework;
#define RTA_MAX_PRIORITY 0
#define RTA_NORMAL_PRIORITY 1
#define RTA_MIN_PRIORITY 2
/**
* Transient states: STARTING, STOPPING. You don't want to block waiting for those
* as you could easily miss them
*
* Example:
* @code
* <#example#>
* @endcode
*/
typedef enum {
FRAMEWORK_INIT = 0, /** Initial status after Create() *
* Example:
* @code
* <#example#>
* @endcode
*/
FRAMEWORK_SETUP = 1, /** Configured in non-threaded mode *
* Example:
* @code
* <#example#>
* @endcode
*/
FRAMEWORK_STARTING = 2, /** Between calling _Start() and the thread running *
* Example:
* @code
* <#example#>
* @endcode
*/
FRAMEWORK_RUNNING = 3, /** After event scheduler thread starts *
* Example:
* @code
* <#example#>
* @endcode
*/
FRAMEWORK_STOPPING = 4, /** When shutdown is finished, but before event scheduler exists *
* Example:
* @code
* <#example#>
* @endcode
*/
FRAMEWORK_TEARDOWN = 5, /** After cleanup from SETUP *
* Example:
* @code
* <#example#>
* @endcode
*/
FRAMEWORK_SHUTDOWN = 6, /** After event scheduler exits *
* Example:
* @code
* <#example#>
* @endcode
*/
} RtaFrameworkStatus;
/**
* Creates the framework context, but does not start the worker thread.
* <code>command_fd</code> is the socketpair or pipe (one-way is ok) over which
* RTATransport will send commands.
*
* Example:
* @code
* <#example#>
* @endcode
*/
RtaFramework *rtaFramework_Create(PARCRingBuffer1x1 *commandRingBuffer, PARCNotifier *commandNotifier);
void rtaFramework_Destroy(RtaFramework **frameworkPtr);
/**
* Returns the Logging system used by the framework
*
* <#Paragraphs Of Explanation#>
*
* @param [in] framework An allocated RtaFramework
*
* @retval non-null The Logging system
*
* Example:
* @code
* <#example#>
* @endcode
*/
RtaLogger *rtaFramework_GetLogger(RtaFramework *framework);
/**
* May block briefly, returns the current status of the framework.
*
* Example:
* @code
* <#example#>
* @endcode
*/
RtaFrameworkStatus rtaFramework_GetStatus(RtaFramework *framework);
/**
* Blocks until the framework status equals or exeeds the desired status
* Transient states: STARTING, STOPPING. You don't want to block waiting for those
* as you could easily miss them
*
* Example:
* @code
* <#example#>
* @endcode
*/
RtaFrameworkStatus rtaFramework_WaitForStatus(RtaFramework *framework,
RtaFrameworkStatus status);
#include "rta_Framework_Threaded.h"
#include "rta_Framework_NonThreaded.h"
#endif
|
