Skip to content

Commit e5b12b2

Browse files
matthiasrichtermatthiasrichter
committed
code documentation and adding man pages for module Algorithm
1 parent 7461f76 commit e5b12b2

4 files changed

Lines changed: 223 additions & 16 deletions

File tree

‎Algorithm/CMakeLists.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,3 +49,6 @@ O2_GENERATE_TESTS(
4949
BUCKET_NAME ${BUCKET_NAME}
5050
TEST_SRCS ${TEST_SRCS}
5151
)
52+
53+
O2_GENERATE_MAN(NAME Algorithm SECTION 3)
54+
O2_GENERATE_MAN(NAME algorithm_parser SECTION 3)

‎Algorithm/doc/Algorithm.3.in‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
.\" Alice O2 manpage for module Algorithm
2+
.TH "AliceO2" 3 "17 Jan 2017" "1.0" "Algorithm man page"
3+
4+
.SH NAME
5+
AliceO2 - module
6+
.B Algorithm
7+
8+
.SH DESCRIPTION
9+
A collection of generic algorithms for Alice O2
10+
11+
.SH SEE ALSO
12+
algorithm_parser(3)

‎Algorithm/doc/algorithm_parser.3.in‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
.\" Alice O2 manpage for parser algorithms
2+
.TH "AliceO2" 3 "17 Jan 2017" "1.0" "Algorithm Parser man page"
3+
4+
.SH NAME
5+
AliceO2 - module
6+
.B Algorithm
7+
- data parsers
8+
9+
.SH SYNOPSIS
10+
.B ForwardParser<
11+
.I SomeHeaderType
12+
,
13+
.I SomeTrailerType
14+
.B >
15+
16+
.B ReverseParser<
17+
.I SomeHeaderType
18+
,
19+
.I SomeTrailerType
20+
.B >
21+
22+
.SS Public types
23+
.TP 2
24+
// a compound of header, data, and trailer
25+
.B struct FrameInfo {
26+
using PtrT = const PayloadType*;
27+
const HeaderType* header = nullptr;
28+
const TrailerType* trailer = nullptr;
29+
PtrT payload = nullptr;
30+
size_t length = 0;
31+
32+
.B };
33+
34+
.TP 2
35+
.B using CheckHeaderFct = std::function<bool(const HeaderType&)>;
36+
alias for callback checking the header, return true if the object is a valid header
37+
.TP 2
38+
.B using CheckTrailerFct = std::function<bool(const TrailerType&)>;
39+
alias for callback checking the trailer
40+
.TP 2
41+
.B using GetFrameSizeFct = std::function<size_t(const HeaderType& )>;
42+
alias for callback to get the complete frame size including header, trailer and the data
43+
.TP 2
44+
.B using InsertFct = std::function<bool(FrameInfo&)>;
45+
function callback to insert/handle one frame into, sequentially called for all frames if the whole block has a valid format
46+
47+
.SS Public member functions
48+
.TP 2
49+
.B template<typename InputType>
50+
.B int parse(const InputType* \fIbuffer\fB, size_t \fIbufferSize\fB, CheckHeaderFct \fIcheckHeader\fB, CheckTrailerFct \fIcheckTrailer\fB, GetFrameSizeFct \fIgetFrameSize\fB, InsertFct \fIinsert\fB)
51+
52+
.SS Public member variables
53+
.TP 2
54+
.B static const size_t headOffset = typesize<HeaderType>::size;
55+
the length offset due to header
56+
.TP 2
57+
.B static const size_t tailOffset = typesize<TrailerType>::size;
58+
the length offset due to trailer
59+
.TP 2
60+
.B static const size_t totalOffset = headOffset + tailOffset;
61+
total length offset due to header and trailer
62+
63+
.SH DESCRIPTION
64+
Template utilities for parsing of data sequences. Each entry in the sequence consist of a header, variable payload, and optionally a trailer. The three parts are collected in the FrameInfo structure for every entry.
65+
66+
Callback functions for checking header and trailer integrity, getting length of the current frame and handling of a frame.
67+
68+
.SS ForwardParser
69+
The size is expected to be part of the header, parsing starts at beginning of buffer.
70+
Trailer type can be void, which is also the default template parameter. That
71+
allows to define a frame consisting of only header and data.
72+
73+
.SS ReverseParser
74+
The size is expected to be part of the trailer, the parsing is thus in reverse direction. Also the insert callback is called with the entries starting form the end of the buffer.
75+
An easy extension can be to reverse the order of the inserts, meaning that the entries are read from the beginning.
76+
77+
.SH EXAMPLES
78+
.SS ReverseParser example
79+
.EX
80+
using SomeParser = ReverseParser<SomeHeaderType, SomeTrailerType>;
81+
SomeParser parser;
82+
std::vector<typename SomeParser::FrameInfo> frames;
83+
parser.parse(ptr, size,
84+
[] (const typename SomeParser::HeaderType& h) {
85+
// check the header
86+
return true;
87+
},
88+
[] (const typename SomeParser::TrailerType& t) {
89+
// check the trailer
90+
return true;
91+
},
92+
[] (const typename SomeParser::TrailerType& t) {
93+
// get the size of the frame including payload
94+
// and header and trailer size, e.g. payload size
95+
// from a trailer member
96+
return t.payloadSize + SomeParser::totalOffset;
97+
},
98+
[&frames] (typename SomeParser::FrameInfo& info) {
99+
frames.emplace_back(info);
100+
return true;
101+
}
102+
)
103+
.EE
104+
105+
.SS ForwardParser example with frame consisting of header and payload
106+
.EX
107+
using SomeParser = ForwardParser<SomeHeaderType>;
108+
SomeParser parser;
109+
std::vector<typename SomeParser::FrameInfo> frames;
110+
parser.parse(ptr, size,
111+
[] (const typename SomeParser::HeaderType& h) {
112+
// check the header
113+
return true;
114+
},
115+
[] (const typename SomeParser::HeaderType& h) {
116+
// get the size of the frame including payload
117+
// and header and trailer size, e.g. payload size
118+
// from a header member
119+
return h.payloadSize + SomeParser::totalOffset;
120+
},
121+
[&frames] (typename SomeParser::FrameInfo& info) {
122+
frames.emplace_back(info);
123+
return true;
124+
}
125+
)
126+
.EE
127+
128+
.SH BUGS, CONTRIBUTIONS
129+
Please add an issue to
130+
.UR https://github.com/AliceO2Group/AliceO2/issues
131+
.UE
132+
133+
.SH SEE ALSO
134+
.UR https://github.com/AliceO2Group/AliceO2/blob/dev/Algorithm/include/Algorithm/Parser.h
135+
.UE

‎Algorithm/include/Algorithm/Parser.h‎

Lines changed: 73 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,13 @@ namespace o2 {
2323

2424
namespace algorithm {
2525

26-
// TODO there is probably a standard way?
26+
/// helper function returning size of type with a specialization for
27+
/// void returning 0
2728
template<typename T>
2829
struct typesize {
2930
static const size_t size = sizeof(T);
3031
};
32+
// specialization for void
3133
template<>
3234
struct typesize<void> {
3335
static const size_t size = 0;
@@ -38,8 +40,12 @@ struct typesize<void> {
3840
* Parser for a sequence of frames with header, trailer and variable payload.
3941
* The size is expected to be part of the header.
4042
*
43+
* Trailer type can be void, which is also the default template parameter. That
44+
* allows to define a frame consisting of only header and data.
45+
*
4146
* Usage:
42-
* ForwardParser<SomeHeaderType, SomeTrailerType> SomeParser;
47+
* <pre>
48+
* using SomeParser = ForwardParser<SomeHeaderType, SomeTrailerType>;
4349
* SomeParser parser;
4450
* std::vector<typename SomeParser::FrameInfo> frames;
4551
* parser.parse(ptr, size,
@@ -62,6 +68,28 @@ struct typesize<void> {
6268
* return true;
6369
* }
6470
* )
71+
*
72+
* // a reduced version without trailer check callback
73+
* using SomeParser = ForwardParser<SomeHeaderType>;
74+
* SomeParser parser;
75+
* std::vector<typename SomeParser::FrameInfo> frames;
76+
* parser.parse(ptr, size,
77+
* [] (const typename SomeParser::HeaderType& h) {
78+
* // check the header
79+
* return true;
80+
* },
81+
* [] (const typename SomeParser::HeaderType& h) {
82+
* // get the size of the frame including payload
83+
* // and header and trailer size, e.g. payload size
84+
* // from a header member
85+
* return h.payloadSize + SomeParser::totalOffset;
86+
* },
87+
* [&frames] (typename SomeParser::FrameInfo& info) {
88+
* frames.emplace_back(info);
89+
* return true;
90+
* }
91+
* )
92+
* </pre>
6593
*/
6694
template<typename HeaderT,
6795
typename TrailerT = void
@@ -72,6 +100,8 @@ class ForwardParser {
72100
using TrailerType = TrailerT;
73101
using PayloadType = unsigned char;
74102

103+
/// @struct FrameInfo
104+
/// a compound of header, data, and trailer
75105
struct FrameInfo {
76106
using PtrT = const PayloadType*;
77107

@@ -81,37 +111,42 @@ class ForwardParser {
81111
size_t length = 0;
82112
};
83113

84-
// the length offset due to header and trailer
114+
/// the length offset due to header
85115
static const size_t headOffset = typesize<HeaderType>::size;
116+
/// the length offset due to trailer
86117
static const size_t tailOffset = typesize<TrailerType>::size;
118+
/// total length offset due to header and trailer
87119
static const size_t totalOffset = headOffset + tailOffset;
88120

89-
// alias for callback checking the header, return true if the object
90-
// is a valid header
121+
/// alias for callback checking the header, return true if the object
122+
/// is a valid header
91123
using CheckHeaderFct = std::function<bool(const HeaderType&)>;
92124

93-
// alias for the argument type to be used in the CheckTrailer function
94-
// have to forward to a valid type in case of void TrailerType in order
95-
// to allow passing by reference
125+
/// alias for the argument type to be used in the CheckTrailer function
126+
/// have to forward to a valid type in case of void TrailerType in order
127+
/// to allow passing by reference
96128
using CheckTrailerFctArgumentT = typename std::conditional<
97129
!std::is_void<TrailerType>::value, TrailerType, int>::type;
98130

99-
// alias for callback checking the trailer, takes reference to trailer
100-
// object if TrailerType is a valid type, no argument otherwise
131+
/// alias for callback checking the trailer, takes reference to trailer
132+
/// object if TrailerType is a valid type, no argument otherwise
101133
template <typename U>
102134
using CheckTrailerFct = typename std::conditional<
103135
!std::is_void<U>::value,
104136
std::function<bool(const CheckTrailerFctArgumentT&)>,
105137
std::function<bool()>>::type;
106138

107-
// alias for callback to get the complete frame size including header,
108-
// trailer and the data
139+
/// alias for callback to get the complete frame size including header,
140+
/// trailer and the data
109141
using GetFrameSizeFct = std::function<size_t(const HeaderType& )>;
110142

111-
// function callback to insert/handle one frame into, sequentially called
112-
// for all frames if the whole block has a valid format
143+
/// function callback to insert/handle one frame into, sequentially called
144+
/// for all frames if the whole block has a valid format
113145
using InsertFct = std::function<bool(FrameInfo&)>;
114146

147+
/// Parse buffer of size bufferSize, requires callbacks to check header
148+
/// trailer, the frame size, and insert callback to handle a FrameInfo
149+
/// object.
115150
template<typename InputType>
116151
int parse(const InputType* buffer, size_t bufferSize,
117152
CheckHeaderFct checkHeader,
@@ -172,6 +207,10 @@ class ForwardParser {
172207
return -1;
173208
}
174209

210+
/// Parse buffer of size bufferSize, specialization skipping the trailer
211+
/// check, e.g. when its type is void, or when the integrity of the trailer
212+
/// is not relevant. Requires callbacks to check header, frame size, and
213+
/// insert callback to handle a FrameInfo object.
175214
template<typename InputType, typename U = TrailerType>
176215
typename std::enable_if<std::is_void<U>::value, int>::type
177216
parse(const InputType* buffer, size_t bufferSize,
@@ -183,6 +222,8 @@ class ForwardParser {
183222
}
184223

185224
private:
225+
/// internal function to check the trailer, distinguishes void and non-void
226+
/// trailer type.
186227
template <typename U = TrailerType>
187228
typename std::enable_if<!std::is_void<U>::value, bool>::type
188229
CheckTrailer(const FrameInfo& entry, CheckTrailerFct<TrailerType>& checkTrailer) const {
@@ -200,10 +241,14 @@ class ForwardParser {
200241
* @class ReverseParser
201242
* Parser for a sequence of frames with header, trailer and variable payload.
202243
* The size is expected to be part of the trailer, the parsing is thus in
203-
* reverse direction.
244+
* reverse direction. Also the insert callback is called with the entries
245+
* starting form the end of the buffer.
246+
* TODO: an easy extension can be to reverse the order of the inserts, meaning
247+
* that the entries are read from the beginning.
204248
*
205249
* Usage:
206-
* ReverseParser<SomeHeaderType, SomeTrailerType> SomeParser;
250+
* <pre>
251+
* using SomeParser = ReverseParser<SomeHeaderType, SomeTrailerType>;
207252
* SomeParser parser;
208253
* std::vector<typename SomeParser::FrameInfo> frames;
209254
* parser.parse(ptr, size,
@@ -226,6 +271,7 @@ class ForwardParser {
226271
* return true;
227272
* }
228273
* )
274+
* </pre>
229275
*/
230276
template<typename HeaderT, typename TrailerT>
231277
class ReverseParser {
@@ -234,6 +280,7 @@ class ReverseParser {
234280
using TrailerType = TrailerT;
235281
using PayloadType = unsigned char;
236282

283+
/// @struct FrameInfo a compound of header, data, and trailer
237284
struct FrameInfo {
238285
using PtrT = const PayloadType*;
239286

@@ -249,11 +296,21 @@ class ReverseParser {
249296
/// total length offset due to header and trailer
250297
static const size_t totalOffset = headOffset + tailOffset;
251298

299+
/// alias for callback checking the header, return true if the object
300+
/// is a valid header
252301
using CheckHeaderFct = std::function<bool(const HeaderType&)>;
302+
/// alias for callback checking the trailer
253303
using CheckTrailerFct = std::function<bool(const TrailerType&)>;
304+
/// alias for callback to get the complete frame size including header,
305+
/// trailer and the data
254306
using GetFrameSizeFct = std::function<size_t(const TrailerType&)>;
307+
/// function callback to insert/handle one frame into, sequentially called
308+
/// for all frames if the whole block has a valid format
255309
using InsertFct = std::function<bool(const FrameInfo&)>;
256310

311+
/// Parse buffer of size bufferSize, requires callbacks to check header
312+
/// trailer, the frame size, and insert callback to handle a FrameInfo
313+
/// object.
257314
template<typename InputType>
258315
int parse(const InputType* buffer, size_t bufferSize,
259316
CheckHeaderFct checkHeader,

0 commit comments

Comments
 (0)