-
Notifications
You must be signed in to change notification settings - Fork 19
/
Copy pathREADME.html
498 lines (478 loc) · 40.4 KB
/
README.html
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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
<HTML><HEAD><TITLE>MUSCLE: (Multi User Server Client Linking Environment)</TITLE></HEAD><BODY BGCOLOR=#ffffff>
<H2>
MUSCLE: Crossbar Server, Portable Messaging and Support Classes<p>
12/31/2024 v9.50 [email protected]<p>
Jeremy Friesner / Meyer Sound Laboratories Inc.<p>
Win32 compatibility contributions by Vitaliy Mikitchenko<p>
C# client code by Wilson Yeung<p>
SSL support code contributed by Nathan Whitehorn
</H2>
<p>
Note: The easiest way to compile is via cmake, e.g.:
<pre>
cd muscle
mkdir _build
cd _build
cmake ..
cmake --build . -j8
</pre>
However, Makefiles are also available, so if you prefer to do
things the old-fashioned way, you can just cd to the directory
you want to build and enter make, e.g.:
<pre>
cd muscle/server
make -j8
</pre>
The server executable, "muscled", should be generated. You can run
this server from the command line, (type "muscled help" to get info
about some options) and connect to it with any MUSCLE-aware program.
<p>
Alternatively, if you prefer a server that runs as a GUI program
and you have Qt installed, you can cd to the "platform/qt/qt_muscled"
subdirectory and type "qmake; make". A GUI server program named
qt_muscled will be created.
<p>
The main goal of these classes is to provide an easy way to use
BMessage-style message passing across a network of heterogeneous
(MacOS/X, Linux, Windows, BSD, Unix, etc) systems. The secondary goal
is just to provide some handy data containers and other utility classes.
<p>
All of this code should compile under any up-to-date C++ compiler--
no proprietary APIs are used except inside of the appropriate #ifdefs.
<p>
For better documentation than this, please see the <a href="https://public.msli.com/lcs/muscle/">MUSCLE web site</a>.
<p>
This code has been compiled and tested in the following environments:
<p>
<ol>
<li>SUSE, Debian, and Ubuntu Linux on various 32-bit and 64-bit PCs</li>
<li>MacOS/X on various PowerPC, Intel, and ARM-based Macs</li>
<li>Microsoft Windows 7, Windows 10, and Windows 11 using Visual Studio 2008 or newer (via cmake)</li>
</ol>
<p>
It has no known bugs, but may have some yet-to-be-discovered ones.
Use at your own risk, Meyer Sound is not responsible for any disasters, blah blah blah.
<p>
Directory contents descriptions follow:
<p>
<ol>
<li>
<b>dataio/</b>
<p>
This directory contains the <a href="dataio/DataIO.h">DataIO</a> interface class, which is an abstraction
for any file-like device that can read or write sequences of bytes, and
(optionally) seek to a specified position. The <a href="dataio/DataIO.h">DataIO</a> class defines an
interface for devices that you can Read() bytes from or Write() bytes to.
This folder also includes some useful implementations of the <a href="dataio/DataIO.h">DataIO</a> interface,
including the following:
<p>
<table>
<tr><td><a href="dataio/AsyncDataIO.h">AsyncDataIO</a></td><td>Wrapper that delegates I/O calls to an internal I/O thread</td></tr>
<tr><td><a href="dataio/ByteBufferDataIO.h">ByteBufferDataIO</a></td><td>For file-style reading/writing to a ByteBuffer held in memory</td></tr>
<tr><td><a href="dataio/ByteBufferPacketDataIO.h">ByteBufferPacketDataIO</a></td><td>Like ByteBufferDataIO, but implements a PacketDataIO interface instead</td></tr>
<tr><td><a href="dataio/ChildProcessDataIO.h">ChildProcessDataIO</a></td><td>For launching a child process and communicating with it via its stdout/stdin</td></tr>
<tr><td><a href="dataio/FileDataIO.h">FileDataIO</a></td><td>For reading/writing via a C (FILE *) file handle</td></tr>
<tr><td><a href="dataio/FileDescriptorDataIO.h">FileDescriptorDataIO</a></td><td>For reading/writing via a Unix file descriptor</td></tr>
<tr><td><a href="dataio/MultiDataIO.h">MultiDataIO</a></td><td>Multiplexer wrapper class for writing to multiple outputs at once</td></tr>
<tr><td><a href="dataio/NullDataIO.h">NullDataIO</a></td><td>Dummy class for directing data to the bit-bucket</td></tr>
<tr><td><a href="dataio/PacketDataIO.h">PacketDataIO</a></td><td>Extended DataIO interface for UDP-like semantics</td></tr>
<tr><td><a href="dataio/PacketizedProxyDataIO.h">PacketizedProxyDataIO</a></td><td>Wrapper for making a TCP connection act like a "reliable UDP connection"</td></tr>
<tr><td><a href="dataio/ProxyDataIO.h">ProxyDataIO</a></td><td>Passes all method-calls through to a "child" DataIO object.</td></tr>
<tr><td><a href="dataio/RS232DataIO.h">RS232DataIO</a></td><td>For communicating via an RS-232 serial port</td></tr>
<tr><td><a href="dataio/SeekableDataIO.h">SeekableDataIO</a></td><td>Extended DataIO interface for file-like semantics</td></tr>
<tr><td><a href="dataio/SSLSocketDataIO.h">SSLSocketDataIO</a></td><td>For communicating over SSL over TCP</td></tr>
<tr><td><a href="dataio/SimulatedMulticastDataIO.h">SimulatedMulticastDataIO</a></td><td>For Wi-Fi; simulates multicast semantics using mostly unicast packets</td></tr>
<tr><td><a href="dataio/StdinDataIO.h">StdinDataIO</a></td><td>For reading from stdin</td></tr>
<tr><td><a href="dataio/TCPSocketDataIO.h">TCPSocketDataIO</a></td><td>For communicating using a TCP socket</td></tr>
<tr><td><a href="dataio/UDPSocketDataIO.h">UDPSocketDataIO</a></td><td>For communicating using a UDP socket</td></tr>
<tr><td><a href="dataio/XorProxyDataIO.h">XorProxyDataIO</a></td><td>Wrapper class that applies XOR-"encryption" to all data that flows through it</td></tr>
</table>
<p>
</li>
<li>
<b>html/</b>
<p>
This directory contains various HTML documentation for the MUSCLE project,
including the Beginner's Guide to MUSCLE, a document on how to create
custom MUSCLE servers, a directory of simple toy example programs,
and the autodoc folder that contains files useful for creating API
documentation using the DOxygen documentation tool.
<p>
</li>
<li>
<b>iogateway/</b>
<p>
This directory contains the AbstractMessageIOGateway interface.
An AbstractMessageIOGateway is a "gateway" object that knows
how to manage bidirectional FIFO Message-stream traffic going to and
coming from a DataIO object. A gateway object queues outgoing MessageRefs,
and when there is room in the outgoing buffer to send one, it flattens the
next MessageRef in the outgoing-message-queue into a sequence of bytes,
and sends those bytes out via the DataIO object. It also reads bytes
coming in from the DataIO object and assembles those bytes back into
<a href="message/Message.h">Message</a> objects, which are then handed back to the AbstractGatewayMessageReceiver
specified by the calling code.
This directory also contains some useful implementations of the
AbstractMessageIOGateway interfaces, which are as follows:
<p>
<table>
<tr><td><a href="iogateway/MessageIOGateway.h">MessageIOGateway</a></td><td>Flattens <a href="message/Message.h">Messages</a> to the standard MUSCLE flattened-message binary format</td></tr>
<tr><td><a href="iogateway/PlainTextMessageIOGateway.h">PlainTextMessageIOGateway</a></td><td>Converts free-form lines of ASCII text into <a href="message/Message.h">Messages</a>, and vice versa</td></tr>
<tr><td><a href="iogateway/RawDataMessageIOGateway.h">RawDataMessageIOGateway</a></td><td>Converts arbitrary raw data into <a href="message/Message.h">Messages</a>, and vice versa</td></tr>
<tr><td><a href="iogateway/SLIPFramedDataMessageIOGateway.h">SLIPFramedDataMessageIOGateway</a></td><td>Similar to the RawDataMessageIOGateway class, except it uses SLIP framing conventions</td></tr>
<tr><td><a href="iogateway/SSLSocketAdapterGateway.h">SSLSocketAdapterGateway</a></td><td>An adapter class to provide transparent support for OpenSSL's particular I/O needs</td></tr>
<tr><td><a href="iogateway/SignalMessageIOGateway.h">SignalMessageIOGateway</a></td><td>Dummy gateway that doesn't send actual data, only indicates when data is available</td></tr>
<tr><td><a href="iogateway/TemplatingMessageIOGateway.h">TemplatingMessageIOGateway</a></td><td>A specialized MessgeIOGateway class that sends <a href="message/Message.h">Messages</a>' metadata separately from their payload data, to reduce bandwidth</td></tr>
<tr><td><a href="iogateway/PacketTunnelIOGateway.h">PacketTunnelIOGateway</a></td><td>Flattens <a href="message/Message.h">Messages</a> into a series of fixed-size packets suitable for UDP transmission</td></tr>
<tr><td><a href="iogateway/MiniPacketTunnelIOGateway.h">MiniPacketTunnelIOGateway</a></td><td>A lightweight version of PacketTunnelIOGateway that supports small <a href="message/Message.h">Messages</a> only</td></tr>
<tr><td><a href="iogateway/ProxyIOGateway.h">ProxyIOGateway</a></td><td>A semi-abstract class with routines to implement calling out to a "child" I/O gateway</td></tr>
</table>
<p>
</li>
<li>
<b>lang/</b>
<p>
This directory contains the MUSCLE client APIs written for the various
programming languages other than C++. Languages currently supported are:
C, C#, Delphi, Java, Java/J2ME, Python2, and Python3.
<p>
</li>
<li>
<b>message/</b>
<p>
This directory contains MUSCLE's <a href="message/Message.h">Message</a> class. A <a href="message/Message.h">Message</a> is a general-purpose
data structure that is similar to BeOS's BMessage class. A <a href="message/Message.h">Message</a> consists
of a 32-bit integer "what code", plus zero or more named data fields, each of
which can contain one or more data items of a specified type.
<p>
Here are some relevant details:
<p>
<ol>
<li>
MUSCLE messages support the following field types:
<p>
<table>
<tr><td>int8</td><td>B_INT8_TYPE</td><td>8-bit signed integer values</td></tr>
<tr><td>int16</td><td>B_INT16_TYPE</td><td>16-bit signed integer values</td></tr>
<tr><td>int32</td><td>B_INT32_TYPE</td><td>32-bit signed integer values</td></tr>
<tr><td>int64</td><td>B_INT64_TYPE</td><td>64-bit signed integer values</td></tr>
<tr><td>bool</td><td>B_BOOL_TYPE</td><td>boolean values</td></tr>
<tr><td>float</td><td>B_FLOAT_TYPE</td><td>IEEE 754 floating point values</td></tr>
<tr><td>Pointer</td><td>B_POINTER_TYPE</td><td>Pointer values (non-flattenable)</td></tr>
<tr><td><a href="message/Message.h">Message</a></td><td>B_MESSAGE_TYPE</td><td><a href="message/Message.h">Message</a> objects</td></tr>
<tr><td><a href="support/Flattenable.h">Flattenable</a></td><td>(various types)</td><td>Flattened <a href="support/Flattenable.h">Flattenable</a> objects</td></tr>
<tr><td><a href="util/String.h">String</a></td><td>B_STRING_TYPE</td><td>UTF8 character strings</td></tr>
<tr><td><a href="support/Rect.h">Rect</a></td><td>B_RECT_TYPE</td><td><a href="support/Rect.h">Rectangles</a> (floats for left,top,right,bottom)</td></tr>
<tr><td><a href="support/Point.h">Point</a></td><td>B_POINT_TYPE</td><td><a href="support/Point.h">Points</a> (floats for x,y)</td></tr>
<tr><td>Raw Data Buffer</td><td>B_RAW_TYPE</td><td>Sequences of zero or more untyped bytes<td></tr>
<tr><td>Tag</td><td>B_TAG_TYPE</td><td>User-provided arbitrary objects (non-flattenable)</td></tr>
</table>
<p>
<li>
<a href="message/Message.h">Message</a> is a subclass of Flattenable (see below), and therefore a <a href="message/Message.h">Message</a> can be serialized
into a "flattened" buffer-of-bytes, which can be sent across a network or saved to a file,
and later the bytes can be unflattened back into an equivalent <a href="message/Message.h">Message</a> object. This is the
basis for most MUSCLE network communication. The flattening and unflattening is endian-aware,
so that e.g. a PowerPC machine can communicate with an Intel machine without problems.
</li>
<li>
<a href="message/Message.h">Message</a> has a GetFieldNameIterator() method, which returns
a MessageFieldNameIterator object, which can be used to
iterate over the fields of a Message.
</li>
</ol>
</li>
<p>
<li>
<b>platform/emscripten/</b>
<p>
This directory contains several classes that support C++ code that is compiled to JavaScript or WebAssembly using the Emscripten SDK.
<p>
<table>
<tr><td><a href="platform/emscripten/EmscriptenAsyncCallback.h">EmscriptenAsyncCallback</a></td><td>A wrapper class for managing Emscripten's asynchronous-callback mechanism.</td></tr>
<tr><td><a href="platform/emscripten/EmscriptenCallbackMechanism.h">EmscriptenCallbackMechanism</a></td><td>An EmscriptenAsyncCallback-based implementation of the <a href="util/ICallbackMechanism.h">ICallbackMechanism</a> interface.</td></tr>
<tr><td><a href="platform/emscripten/EmscriptenReflectServer.h">EmscriptenReflectServer</a></td><td>A specialization of <a href="reflector/ReflectServer.h">ReflectServer</a> that uses an EmscriptenAsyncCallback to drive its ServerEventLoop.</td></tr>
<tr><td><a href="platform/emscripten/EmscriptenWebSocketDataIO.h">EmscriptenWebSocketDataIO</a></td><td>An implementation of <a href="dataio/DataIO.h">DataIO</a> that uses Emscripten's asynchronous websocket APIs to send and receive data.</td></tr>
</table>
<p>
</li>
<li>
<b>platform/qt/</b>
<p>
This directory contains several classes that support clients that use TrollTech's
Qt cross-platform GUI API. The main one is the QMessageTransceiverThread class,
which is a Qt-aware subclass of the MessageTransceiverThread class.
Using a QMessageTransceiverThread for your network I/O makes network communication
very simple; instead of dealing with bytes and network protocols, you simply
receive a Qt signal whenever incoming <a href="message/Message.h">Messages</a> are available, and call a method to
send a Message, etc.
This folder also contains some sub-directories that contain small example
programs written for MUSCLE+Qt:
<p>
<table>
<tr><td>qt_example</td><td>A simple multi-user 'game' and chat program</td></tr>
<tr><td>qt_advanced_example</td><td>A demonstration of embedding a MUSCLE server thread inside a Qt application</td></tr>
<tr><td>qt_muscled</td><td>A demonstration of a Qt app that runs a MUSCLE server as a child process</td></tr>
<tr><td>qt_muscled_browser</td><td>A hierarchical browser GUI for seeing what data is present in a muscle server's database</td></tr>
</table>
<p>
</li>
<li>
<b>reflector/</b>
<p>
This directory contains server code for an n-way
"message crossbar server" program. This program will listen
on a specified port for TCP connections, and will allow the
TCP connections to "talk to each other" by forwarding <a href="message/Message.h">Messages</a> from
one client to another (or to multiple others).
The ServerProcessLoop() method implements the server's event loop,
while the <a href="reflector/AbstractReflectSession.h">AbstractReflectSession</a> class is the interface for the server's side
of a TCP connection. There are currently two subclasses of
<a href="reflector/AbstractReflectSession.h">AbstractReflectSession</a> included: the <a href="reflector/DumbReflectSession.h">DumbReflectSession</a>
class just reflects all received <a href="message/Message.h">Messages</a> to all connected clients, while
the <a href="reflector/StorageReflectSession.h">StorageReflectSession</a> class adds nice features like wildcard-based
<a href="message/Message.h">Message</a> routing, server-side data storage, and "notify-me-on-change"
subscription services. (See the MUSCLE Beginner's Guide for more info on this)
More elaborate logic can be added by creating subclasses of these classes.
<p>
</li>
<li>
<b>regex/</b>
<p>
This directory contains code to support the use of regular expressions.
This includes some C++ pattern-matching utility classes, as well as a
sub-folder containing Henry Spencer's freeware C regex engine, for use
in OS's that do not provide their own regex library.
<p>
Classes implemented in this directory include:
<p>
<table>
<tr><td><a href="regex/FilePathExpander.h">FilePathExpander</a></td><td>Expands shell-style wildcards into a list of file paths</td></tr>
<tr><td><a href="regex/PathMatcher.h">PathMatcher</a></td><td>Controls wildcard-directed recursive iterations down the tree of DataNode objects</td></tr>
<tr><td><a href="regex/QueryFilter.h">QueryFilter</a></td><td>Implements various predicate-logic operations on DataNode <a href="message/Message.h">Message</a> data</td></tr>
<tr><td><a href="regex/StringMatcher.h">StringMatcher</a></td><td>Does shell-style pattern matching on arbitrary character strings</td></tr>
<tr><td><a href="regex/SegmentedStringMatcher.h">SegmentedStringMatcher</a></td><td>Like StringMatcher, except that the strings are divided up into substrings which are evaluated separately (e.g. "a*/b*")</td></tr>
</table>
<p>
</li>
<li>
<b>server/</b>
<p>
This contains the Makefile and main entry point for the "muscled"
server executable, and the "admin" muscled-server-administration utility.
<p>
</li>
<li>
<b>support/</b>
<p>
This directory contains various "small things" needed to compile the rest of the code.
<p>
Classes implemented in this directory include:
<p>
<table>
<tr><td><a href="support/BitChord.h">BitChord</a></td><td>Implements an ordered set of N individually-settable binary bits</td></tr>
<tr><td><a href="support/DataFlattener.h">DataFlattener</a></td><td>A lightweight helper-object for writing out endian-encoded data to a raw binary buffer.</td></tr>
<tr><td><a href="support/DataUnflattener.h">DataUnflattener</a></td><td>A lightweight helper-object for reading in endian-encoded data from a raw binary buffer.</td></tr>
<tr><td><a href="support/Flattenable.h">Flattenable</a></td><td>Interface for an object that can be "Flattened" into a serialized-binary representation, and Unflattened back again</td></tr>
<tr><td><a href="support/PseudoFlattenable.h">PseudoFlattenable</a></td><td>Same as Flattenable, but without the virtual methods. Used as a tag for objects that can be flattened without runtime polymorphism</td></tr>
<tr><td><a href="support/NotCopyable.h">NotCopyable</a></td><td>Inheriting from this class tells the compiler not to allow copies to made of objects of your subclass</td></tr>
<tr><td><a href="support/Point.h">Point</a></td><td>A two-float x/y Point class</td></tr>
<tr><td><a href="support/Rect.h">Rect</a></td><td>A four-float left/top/width/height Rectangle class</td></tr>
<tr><td><a href="support/TamperEvidentValue.h">TamperEvidentValue</a></td><td>Templatized holder for an arbitrary object that will set a flag whenever the object is modified<td></td></tr>
<tr><td><a href="support/Tuple.h">Tuple</a></td><td>Templatized class that holds a fixed-size array of N same-typed values</td></tr>
<tr><td><a href="support/Void.h">Void</a></td><td>Placeholder class that contains no data</td></tr>
</table>
<p>
</li>
<li>
<b>syslog/</b>
<p>
This directory contains functions for logging event messages to stdout
and/or to a file. Log messages can be "raw" (works just like printf)
or nicely formatted with the current time, redirected to a file, and so
on. The logging system also has optional functionality to rotate, compress
and/or delete old log files, to avoid filling up too much disk space.
<p>
</li>
<li>
<b>system/</b>
<p>
This directory contains classes that represent "generic" interfaces
to OS-specific APIs; as such, they are not guaranteed to work on
every platform (but generally will work on at least Windows, Linux, and MacOS/X).
Currently this directory contains the following classes:
<p>
<table>
<tr><td><a href="system/AtomicCounter.h">AtomicCounter</a></td><td>Atomic-increment and atomic-decrement counter, for lock-free reference-counting</td</tr>
<tr><td><a href="system/AtomicValue.h">AtomicValue</a></td><td>A lock-free way to update a non-trivial object that is shared between multiple different threads</td</tr>
<tr><td><a href="system/DetectNetworkConfigChangesSession.h">DetectNetworkConfigChangesSession</a></td><td>A session object that notifies the program when the host computer's network configuration has changed</td</tr>
<tr><td><a href="system/GlobalMemoryAllocator.h">GlobalMemoryAllocator</a></td><td>Code to monitor and optionally restrict the program's heap usage</td</tr>
<tr><td><a href="system/MessageTransceiverThread.h">MessageTransceiverThread</a></td><td>Runs a MUSCLE <a href="reflector/ReflectServer.h">ReflectServer</a> object in a separate thread. Provides asynchronous I/O</td</tr>
<tr><td><a href="system/Mutex.h">Mutex</a></td><td>Provides efficient in-process locking (aka critical sections) for thread-safety</td</tr>
<tr><td><a href="system/ReaderWriterMutex.h">ReaderWriterMutex</a></td><td>Implementation of a recursive Reader/Writer lock</td</tr>
<tr><td><a href="system/SetupSystem.h">SetupSystem</a></td><td>Provides standardized startup and shutdown routines that must be used by any MUSCLE process</td</tr>
<tr><td><a href="system/SharedMemory.h">SharedMemory</a></td><td>Implements inter-process shared memory regions, including inter-process read/write locking ability</td</tr>
<tr><td><a href="system/SpinLock.h">SpinLock</a></td><td>Like a Mutex, but avoids context-switching by busy-looping until the lock is obtained.</td</tr>
<tr><td><a href="system/SignalMultiplexer.h">SignalMultiplexer</a></td><td>Makes system signalling (e.g. catching of SIGINT or SIHUP) available to multiple pieces of code in the same process</td</tr>
<tr><td><a href="system/SystemInfo.h">SystemInfo</a></td><td>Provides information about the environment the program is operating in (current directory, OS version, etc)</td</tr>
<tr><td><a href="system/Thread.h">Thread</a></td><td>An OS-neutral Thread class for multithreading purposes. Includes send/receive <a href="message/Message.h">Message</a> functionality for easy control</td</tr>
<tr><td><a href="system/ThreadLocalStorage.h">ThreadLocalStorage</a></td><td>An OS-neutral implementation of thread-local data storage</td</tr>
<tr><td><a href="system/ThreadPool.h">ThreadPool</a></td><td>A thread pool implementation to allow handling of many <a href="message/Message.h">Messages</a> in parallel across a finite number of threads.</td</tr>
<tr><td><a href="system/WaitCondition.h">WaitCondition</a></td><td>A simple and lightweight thread-notification mechanism based on a condition-variable.</td</tr>
</table>
<p>
</li>
<li>
<b>test/</b>
<p>
This directory contains various unit-test programs that I use to test and develop the code, and a Makefile to build them with
(cmake will build them also, if you specify the "full" configuration or specify -DWITH_TESTS=ON)
There is also a runtests.sh bash script that can be executed to do a quick run-through of all the regression tests in the folder.
<p>
Currently this directory contains the following unit-tests:
<p>
<table>
<tr><td><a href="test/testatomicvalue.cpp">testatomicvalue</a></td><td>Unit test for the AtomicValue class</td></tr>
<tr><td><a href="test/testbatchguard.cpp">testbatchguard</a></td><td>Unit test for the BatchGuard class</td></tr>
<tr><td><a href="test/testbitchord.cpp">testbitchord</a></td><td>Unit test for the BitChord class</td></tr>
<tr><td><a href="test/testbytebuffer.cpp">testbytebuffer</a></td><td>Unit test for the ByteBuffer class</td></tr>
<tr><td><a href="test/testchildprocess.cpp">testchildprocess</a></td><td>Unit test for the ChildProcessDataIO class</td></tr>
<tr><td><a href="test/testclone.cpp">testclone</a></td><td>Unit test for the Cloneable interface</td></tr>
<tr><td><a href="test/testendian.cpp">testendian</a></td><td>Unit test for the endian-swapping routines</td></tr>
<tr><td><a href="test/testfilepathinfo.cpp">testfilepathinfo</a></td><td>Unit test for the FilePathInfo class</td></tr>
<tr><td><a href="test/testgateway.cpp">testgateway</a></td><td>Unit test for the MessageIOGateway class</td></tr>
<tr><td><a href="test/testhashcodes.cpp">testhashcodes</a></td><td>Unit test for the CalculateHashCode() functions</td></tr>
<tr><td><a href="test/testhashtable.cpp">testhashtable</a></td><td>Unit test for the Hashtable class</td></tr>
<tr><td><a href="test/testmatchfiles.cpp">testmatchfiles</a></td><td>Unit test for the ExpandFilePathWildCards() function</td></tr>
<tr><td><a href="test/testmessage.cpp">testmessage</a></td><td>Unit test for the <a href="message/Message.h">Message</a> class</td></tr>
<tr><td><a href="test/testmicro.cpp">testmicro</a></td><td>Unit test for the MicroMessage and MicroMessageGateway C routines</td></tr>
<tr><td><a href="test/testmini.cpp">testmini</a></td><td>Unit test for the MiniMessage and MiniMessageGateway C routines</td></tr>
<tr><td><a href="test/testnagle.cpp">testnagle</a></td><td>Unit test to verify the presence of absence of Nagle's algorithm</td></tr>
<tr><td><a href="test/testnetconfigdetect.cpp">testnetconfigdetect</a></td><td>Unit test for the DetectNetworkConfigChangesSession class</td></tr>
<tr><td><a href="test/testnetutil.cpp">testnetutil</a></td><td>Unit test for the GetNetworkInterfaces() function</td></tr>
<tr><td><a href="test/testobjectpool.cpp">testobjectpool</a></td><td>Unit test for the ObjectPool class</td></tr>
<tr><td><a href="test/testpacketio.cpp">testpacketio</a></td><td>Unit test for the PacketizedDataIO clas</td></tr>
<tr><td><a href="test/testpackettunnel.cpp">testpackettunnel</a></td><td>Unit test for the PacketTunnelIOGateway class</td></tr>
<tr><td><a href="test/testparsefile.cpp">testparsefile</a></td><td>Unit test for the ParseFile() and ParseArgs() functions</td></tr>
<tr><td><a href="test/testpool.cpp">testpool</a></td><td>Unit test for the ObjectPool class</td></tr>
<tr><td><a href="test/testpulsenode.cpp">testpulsenode</a></td><td>Unit test for the PulseNode class</td></tr>
<tr><td><a href="test/testqueryfilter.cpp">testqueryfilter</a></td><td>Unit test for the QueryFilter classes</td></tr>
<tr><td><a href="test/testreaderwritermutex.cpp">testreaderwritermutex</a></td><td>Unit test for the ReaderWriterMutex classes</td></tr>
<tr><td><a href="test/testqueue.cpp">testqueue</a></td><td>Unit test for the Queue class</td></tr>
<tr><td><a href="test/testrefcount.cpp">testrefcount</a></td><td>Unit test for the RefCount class</td></tr>
<tr><td><a href="test/testregex.cpp">testregex</a></td><td>Unit test for the StringMatcher class</td></tr>
<tr><td><a href="test/testresponse.cpp">testresponse</a></td><td>Test to measure the response latency of a muscle server</td></tr>
<tr><td><a href="test/testserial.cpp">testserial</a></td><td>Unit test for the RS232DataIO class</td></tr>
<tr><td><a href="test/testserverthread.cpp">testserverthread</a></td><td>Demonstration of a server that spawns a child thread for asynchronous processing</td></tr>
<tr><td><a href="test/testsharedmem.cpp">testsharedmem</a></td><td>Unit test for the SharedMemory class</td></tr>
<tr><td><a href="test/testsocketmultiplexer.cpp">testsocketmultiplexer</a></td><td>Unit test for the SocketMultiplexer class</td></tr>
<tr><td><a href="test/teststatus.cpp">teststatus</a></td><td>Unit test for the status_t class</td></tr>
<tr><td><a href="test/teststring.cpp">teststring</a></td><td>Unit test for the String class</td></tr>
<tr><td><a href="test/teststringtokenizer.cpp">teststringtokenizer</a></td><td>Unit test for the StringTokenizer class</td></tr>
<tr><td><a href="test/testsysteminfo.cpp">testsysteminfo</a></td><td>Unit test for the SystemInfo functionality</td></tr>
<tr><td><a href="test/testthread.cpp">testthread</a></td><td>Unit test for the Thread class</td></tr>
<tr><td><a href="test/testthreadpool.cpp">testthreadpool</a></td><td>Unit test for the ThreadPool class</td></tr>
<tr><td><a href="test/testtime.cpp">testtime</a></td><td>Unit test for the various time-string-parsing and time-string-generation functions</td></tr>
<tr><td><a href="test/testtimeunitconversions.cpp">testtimeunitconversions</a></td><td>Unit tests for the various time-unit-conversion functions (SecondsToMicros(), etc)</td></tr>
<tr><td><a href="test/testtuple.cpp">testtuple</a></td><td>Unit test for the Tuple class</td></tr>
<tr><td><a href="test/testtypedefs.cpp">testtypedefs</a></td><td>Unit test for MUSCLE's standard type typedefs (int32, int64, etc)</td></tr>
<tr><td><a href="test/testudp.cpp">testudp</a></td><td>Test/demonstration of using MUSCLE to send/receive UDP packets</td></tr>
<tr><td><a href="test/testzip.cpp">testzip</a></td><td>Unit test of the ReadZipFile() and WriteZipFile() functions</td></tr>
</table>
<p>
<p>
</li>
<li>
<b>tools/</b>
<p>
This directory contains various other programs that I wrote while developing MUSCLE, that I found useful enough to include with the repository.
There is also a Makefile to build them with (if you need it; they get built by default by CMake too)
<p>
Currently this directory contains the following programs:
<p>
<table>
<tr><td><a href="tools/bandwidthtester.cpp">bandwidthtester</a></td><td>Generates lots of <a href="message/Message.h">Message</a> traffic and measures how fast a MUSCLE server can receive it</td></tr>
<tr><td><a href="tools/calctypecode.cpp">calctypecode</a></td><td>Prints out the decimal equivalent of a four-character ASCII what-code</td></tr>
<tr><td><a href="tools/chatclient.cpp">chatclient</a></td><td>Minimalist BeShare-compatible chat client that can connect to any MUSCLE server</td></tr>
<tr><td><a href="tools/daemonsitter.cpp">daemonsitter</a></td><td>Demonstration of a program that spawns multiple sub-processes, watches their stdin/stdout, and relaunches them if necessary.</td></tr>
<tr><td><a href="tools/deadlock.cpp">deadlock</a></td><td>Deliberately tries to create a deadlock. Primarily used for testing MUSCLE's built-in deadlock-detection code (in conjunction with the -DWITH_DEADLOCKFINDER cmake option).</td></tr>
<tr><td><a href="tools/erasesharedmem.cpp">erasesharedmem</a></td><td>Utility to delete the shared-memory region with a specified name.</td></tr>
<tr><td><a href="tools/findsourcelocations.cpp">findsourcelocations</a></td><td>Parses source code and lists source-locations matching a specified code generated by MUSCLE's MUSCLE_INCLUDE_SOURCE_CODE_LOCATION_IN_LOGTIME feature</td></tr>
<tr><td><a href="tools/hexterm.cpp">hexterm</a></td><td>A simple interactive terminal that sends, receives, and prints hexadecimal representation of all bytes communicated via TCP, UDP, etc.</td></tr>
<tr><td><a href="tools/multithreadedreflectclient.cpp">multithreadedreflectclient</a></td><td>Similar to singlethreadedreflectclient, but implemented using a CallbackMessageTransceiverThread to handle all I/O)</td></tr>
<tr><td><a href="tools/muscleproxy.cpp">muscleproxy</a></td><td>Demonstration of a pass-through TCP proxy for MUSCLE connections.</td></tr>
<tr><td><a href="tools/portableplaintextclient.cpp">portableplaintextclient</a></td><td>A simple interactive terminal for ASCII communication over TCP</td></tr>
<tr><td><a href="tools/portscan.cpp">portscan</a></td><td>Attempts to connect via TCP to a range of ports on a host, and reports which ports accepted the connection</td></tr>
<tr><td><a href="tools/printsourcelocations.cpp">printsourcelocations</a></td><td>Prints the source-code-location codes of all LogTime() commands. Useful for building up a directory of source-location-codes for a given codebase</td></tr>
<tr><td><a href="tools/printtypecode.cpp">printtypecode</a></td><td>Prints out the four-character ASCII equivalent of a given decimal value</td></tr>
<tr><td><a href="tools/readmessage.cpp">readmessage</a></td><td>Reads a flattened <a href="message/Message.h">Message</a> from a file on disk and prints it to stdout in human-readable form</td></tr>
<tr><td><a href="tools/rwdeadlock.cpp">rwdeadlock</a></td><td>Program to deliberately cause a deadlock using the ReaderWriterMutex class</td></tr>
<tr><td><a href="tools/serialproxy.cpp">serialproxy</a></td><td>Makes a local serial port available to the network over TCP</td></tr>
<tr><td><a href="tools/singlethreadedreflectclient.cpp">singlethreadedreflectclient</a></td><td>A simple interactive terminal for <a href="message/Message.h">Message</a> communication over TCP (typically with a MUSCLE server)</td></tr>
<tr><td><a href="tools/snoopsharedmem.cpp">snoopsharedmem</a></td><td>Program to periodically print out the contents of a specified shared memory region</td></tr>
<tr><td><a href="tools/striphextermoutput.cpp">striphextermoutput</a></td><td>Parses output from hexterm and removes the metadata, leaving behing only the hex values themselves.</td></tr>
<tr><td><a href="tools/udpproxy.cpp">udpproxy</a></td><td>Forwards UDP packets from one computer to another, and vice versa</td></tr>
<tr><td><a href="tools/uploadstress.cpp">uploadstress</a></td><td>Spams a MUSCLE server with requests to see if the server can keep up</td></tr>
</table>
<p>
<p>
</li>
<li>
<b>util/</b>
<p>
This directory contains many useful one-off classes and function collections, including:
<p>
<table>
<tr><td><a href="util/BatchOperator.h">BatchOperator</a></td><td>An RAII mechanism for ensuring that a specified method gets called on the first-level recursion into a call tree, and that a matching method gets called on the final recursion out of the call tree.</td></tr>
<tr><td><a href="util/ByteBuffer.h">ByteBuffer</a></td><td>An intelligent byte-array class, that stores its length, knows how to resize itself efficiently, is reference-countable and flattenable, etc.</td></tr>
<tr><td><a href="util/CountedObject.h">CountedObject</a></td><td>A class that other classes can be derived from if you want to keep track of how many instances of them are in memory at any given time.</td></tr>
<tr><td><a href="util/CPULoadMeter.h">CPULoadMeter</a></td><td>Reports the percentage of CPU time being used on the local computer from moment to moment.</td></tr>
<tr><td><a href="util/DebugTimer.h">DebugTimer</a></td><td>useful for debugging performance problems. It records the current time in its constructor, and then in its destructor it prints out the time that has elapsed since then.</td></tr>
<tr><td><a href="util/Directory.h">Directory</a></td><td>a platform-neutral API for scanning a filesystem directory and iterating over its contents.</td></tr>
<tr><td><a href="util/FilePathInfo.h">FilePathInfo</a></td><td>API for querying the various properties of an entry at a specified location in a file system (e.g. is a file, a directory, or a symlink, how large is it, when was it created or modified, etc)</td></tr>
<tr><td><a href="util/Hashtable.h">Hashtable</a></td><td>A handy hash table class, with templated key and value types and the traditional O(1) lookup time. Includes other nice features, such as "safe" iterators (so you can modify the Hashtable while iterating through it), predictable memory allocations, and the ability to sort the table by key or by value (it maintains the ordering of the objects placed into the table).</td></tr>
<tr><td><a href="util/ICallbackMechanism.h">ICallbackMechanism</a></td><td>Abstract interface for an object that can call a method in the main thread after receiving a trigger-method-call from some other thread.</td></tr>
<tr><td><a href="util/ImmutableHashtablePool.h">ImmutableHashtablePool</a></td><td>A utility class used to reduce memory usage when there are a large number of objects that each need to hold a Hashtable, but many of the held Hashtables will be identical to each other.</td></tr>
<tr><td><a href="util/IncrementalHashCalculator.h">IncrementalHashCalculator</a></td><td>A utility class for incrementally calculating the MD5 or SHA1 hash codes of indefinitely-long byte sequences.</td></tr>
<tr><td><a href="util/IPAddress.h">IPAddress</a></td><td>Represents an IPv4 or IPv6 address in a uniform manner. There is also an IPAddressAndPort class which represents the combination of an IP address and a port number.</td></tr>
<tr><td><a href="util/MiscUtilityFunctions.h">MiscUtilityFunctions</a></td><td>A catch-all for various useful functions that didn't fit anywhere else.</td></tr>
<tr><td><a href="util/NestCount.h">NestCount</a></td><td>RAII class for recording when the execution path enters or exits a particular function, and (optionally) making decisions based on whether a specified function is currently on the stack or not.</td></tr>
<tr><td><a href="util/NetworkUtilityFunctions.h">NetworkUtilityFunctions</a></td><td>A repository of user-friendly wrapper functions around common BSD socket operations, such as setting up sockets to connect or accept TCP connections, or binding a UDP socket to a port.</td></tr>
<tr><td><a href="util/ObjectPool.h">ObjectPool</a></td><td>Slab-allocator-based object-pool class, used to avoid excessive heap access when managing commonly heap-allocated objects (such as <a href="message/Message.h">Message</a> or Socket).</td></tr>
<tr><td><a href="util/PointerAndBits.h">PointerAndBits</a></td><td>Templated class for hiding additional bits of data inside the unused bits of a pointer.</td></tr>
<tr><td><a href="util/PulseNode.h">PulseNode</a></td><td>An interface for objects that want to execute a particular action at a specified time. It works in conjunction with the standard MUSCLE event loop. Implementing classes define a Pulse() method that will be executed at a specified time, and a GetPulseTime() method that returns a clock value indicating when Pulse() should next be executed.</td></tr>
<tr><td><a href="util/Queue.h">Queue</a></td><td>A templatized double-ended/circular queue (i.e. AddHead(), AddTail(), RemoveHead(), and RemoveTail() are O(1) operations). It can be used as a Vector, Stack, or FIFO.</td></tr>
<tr><td><a href="util/RefCount.h">RefCount</a></td><td>Reference-counting shared-pointer class for C++ objects that derive from RefCountable</td></tr>
<tr><td><a href="util/Socket.h">Socket</a></td><td>A reference-countable C++ class wrapper for a socket or file descriptor, used to avoid descriptor leaks</td></tr>
<tr><td><a href="util/SocketCallbackMechanism.h">SocketCallbackMechanism</a></td><td>An <a href="util/ICallbackMechanism.h">ICallbackMechanism</a> based on a BSD socket-pair.</td></tr>
<tr><td><a href="util/SocketMultiplexer.h">SocketMultiplexer</a></td><td>An easy-to-use wrapper around the select() socket-multiplexing API (or similar alternative multiplexing APIs such as poll()/epoll()/kqueue())</td></tr>
<tr><td><a href="util/String.h">String</a></td><td>A basic ASCII/UTF-8 character-string class with SSO.</td></tr>
<tr><td><a href="util/StringTokenizer.h">StringTokenizer</a></td><td>A string-tokenizing class similar to Java's Java.util.StringTokenizer, only more efficient.</td></tr>
<tr><td><a href="util/TimeUnitConversionFunctions.h">TimeUnitConversionFunctions</a></td><td>Inline functions for converting from one time-unit (e.g. milliseconds) to another (e.g. microseconds).</td></tr>
<tr><td><a href="util/TimeUtilityFunctions.h">TimeUtilityFunctions</a></td><td>A repository of functions for dealing with microsecond-accurate timing issues.</td></tr>
<tr><td><a href="util/WaitConditionCallbackMechanism.h">WaitConditionCallbackMechanism</a></td><td>An <a href="util/ICallbackMechanism.h">ICallbackMechanism</a> based on a WaitCondition object.</td></tr>
</table>
<p>
</li>
<li>
<b>zlib/</b>
<p>
This directory holds a subfolder named zlib (which contains the complete source code of Mark Adler's zlib lossless data-compression/decompression library, for use in OS's that don't have that library pre-installed).
This directory also contains some zlib-related APIs, including:
<p>
<table>
<tr><td><a href="zlib/GZDataIO.h">GZDataIO</a></td><td>A DataIO wrapper around zlib's gzread() and gzwrite() API (useful for quick-and dirty blocking-I/O reading/writing of .gz files).</td></tr>
<tr><td><a href="zlib/TarFileWriter.h">TarFileWriter</a></td><td>A class implements writing of .tar data to a file or to a DataIO.</td></tr>
<tr><td><a href="zlib/ZLibCodec.h">ZLibCodec</a></td><td>A programmer-friendly wrapper around zlib's deflation and inflation routines.</td></tr>
<tr><td><a href="zlib/ZLibDataIO.h">ZLibDataIO</a></td><td>A decorator DataIO object that transparently deflates/inflates outgoing/incoming data headed to/from its child DataIO.</td></tr>
<tr><td><a href="zlib/ZLibUtilityFunctions.h">ZLibUtilityFunctions</a></td><td>Various functions for deflating or inflating ByteBuffers full of data easily.</td></tr>
<tr><td><a href="zlib/ZipFileUtilityFunctions.h">ZipFileUtilityFunctions</a></td><td>Functions for loading a .zip file in as a Message object, or saving a Message object as a .zip file.</td></tr>
</table>
<p>
<p>
</li>
</ol>
<p>
For more details, have a look at the <a href="https://public.msli.com/lcs/muscle/html/hierarchy.html">autodocs</a>, header files and/or the source itself.
<p>
-Jeremy