9.44 release

HISTORY.txt

@@ -5,6 +5,7 @@ key:  - new feature
       * bug fixed
       o other
 
+9.44 - Released 12/16/2024
    - Added an optional human-readable name field to ReaderWriterMutex.
    - Added a GetInsecurePseudoRandomNumber() function to MiscUtilityFunctions,
      just to minimize the number of direct calls to rand().

README.html

@@ -2,7 +2,7 @@
 
 <H2>
 MUSCLE:  Crossbar Server, Portable Messaging and Support Classes<p>
-11/22/2024 v9.43 jaf@meyersound.com<p>
+12/16/2024 v9.44 jaf@meyersound.com<p>
 Jeremy Friesner / Meyer Sound Laboratories Inc.<p>
 Win32 compatibility contributions by Vitaliy Mikitchenko<p>
 C# client code by Wilson Yeung<p>
@@ -307,6 +307,7 @@ <H2>
     <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>
@@ -332,6 +333,7 @@ <H2>
    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>
@@ -356,6 +358,7 @@ <H2>
     <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>
@@ -392,21 +395,24 @@ <H2>
     <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/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/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 received via TCP, UDP, etc.</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/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/portableplaintextclient.cpp">portableplaintextclient</a></td><td>A simple interactive terminal for ASCII communication 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/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/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>
@@ -424,17 +430,18 @@ <H2>
     <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/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/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/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/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/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>
@@ -443,6 +450,7 @@ <H2>
     <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>
@@ -462,6 +470,7 @@ <H2>
     <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>

html/Beginners Guide.html

@@ -1,7 +1,7 @@
 <HTML>
 <HEAD>
    <H1>MUSCLE Overview and Beginner's Guide</H1>
-   <H4>v9.43 / Jeremy Friesner / Meyer Sound Laboratories Inc (jaf@meyersound.com) 11/22/2024</H4>
+   <H4>v9.44 / Jeremy Friesner / Meyer Sound Laboratories Inc (jaf@meyersound.com) 12/16/2024</H4>
    <A HREF="https://public.msli.com/lcs/muscle/html/index.html">Click here for DOxygen class API documentation</A><p>
    <A HREF="https://public.msli.com/lcs/muscle/muscle/html/muscle-by-example/site/index.html">Click here for the MUSCLE-by-example tour</A>
 </HEAD>
@@ -25,7 +25,7 @@ <H3>Feature List</H3>
   <LI> <b>Efficient:</b>  Messages sent to the server may be broadcast to all connected clients, or multicast intelligently using pattern-matching and/or boolean filtering logic. </LI>
   <LI> <b>Portable:</b>  All code (except for some platform-specific convenience classes in the support folders) uses only standard C++ and BSD socket calls, and should compile and run under any modern OS with minimal changes.  All code has been compiled and tested on 32-bit and 64-bit platforms including Linux, MacOS/X, Windows, and BSD. </LI>
   <LI> <b>Flexible:</b>  Clients may store data (in the form of Messages) in the server's RAM, using a filesystem-like node hierarchy.  Other clients may "subscribe" to this server-side data, and the server will then automatically send them updates to the data as it is changed.  Subscriptions are also specified via wildcarding, for maximum flexibility.  Server-side filtering of results using boolean tests of their content is also supported.</LI>
-  <LI> <b>Open:</b>  All source code is licensed under the BSD Open Source License, and is freely distributable and usable for any purpose.  The source code contains many useful classes, including platform-neutral analogs to Be's BMessage, BDataIO, BFlattenable, and BString classes.  In addition, the archive also includes handy double-ended-queue, Hashtable, Reference-counting, and "I/O gateway" classes.</LI>
+  <LI> <b>Open:</b>  All source code is licensed under the BSD Open Source License, and is freely distributable and usable for any purpose.  The source code contains many useful classes, including platform-neutral analogs to Be's BMessage, BDataIO, BFlattenable, and BString classes.  In addition, the archive also includes handy double-ended-Queue, Hashtable, Reference-counting, and "I/O gateway" classes.</LI>
   <LI> <b>Customizable:</b>  All server-side session handlers are implemented by subclassing a standard interface (AbstractReflectSession) so that they can be easily augmented or replaced with custom logic.  Message serialization and low-level I/O is handled in a similar fashion, making it easy to replace the byte-stream format or transport mechanism with your own. </LI>
   <LI> <b>Scalable:</b>  A vanilla MUSCLE server can handle up to 1024 simultaneous TCP connections (or more than that if you enable -DMUSCLE_USE_POLL or -DMUSCLE_USE_KQUEUE or -DMUSCLE_USE_EPOLL).  Additional simultaneous connections can be supported in custom MUSCLE servers by adding multiple threads or processes</LI>
   <LI> <b>Convenient:</b>  For selected environments, including Windows, Qt, Java, Delphi, and Python, special utility classes are provided to hide the synchronous TCP messaging interface behind an asynchronous send-and-receive-messages API that's easier to deal with.</LI>

html/Custom Servers.html

@@ -1,7 +1,7 @@
 <HTML>
 <HEAD>
    <H1>Implementing a Custom Server with MUSCLE</H1>
-   <H4>v9.43 / Jeremy Friesner / Meyer Sound Laboratories Inc (jaf@meyersound.com) 11/22/2024</H4>
+   <H4>v9.44 / Jeremy Friesner / Meyer Sound Laboratories Inc (jaf@meyersound.com) 12/16/2024</H4>
 </HEAD>
 <BODY bgcolor=#ffffff>
 <H2>Introduction</H2>

support/MuscleSupport.h

@@ -11,8 +11,8 @@
 /
 *******************************************************************************/
 
-#define MUSCLE_VERSION_STRING "9.43" /**< The current version of the MUSCLE distribution, expressed as an ASCII string */
-#define MUSCLE_VERSION        94300  /**< Current version, expressed as decimal Mmmbb, where (M) is the number before the decimal point, (mm) is the number after the decimal point, and (bb) is reserved */
+#define MUSCLE_VERSION_STRING "9.44" /**< The current version of the MUSCLE distribution, expressed as an ASCII string */
+#define MUSCLE_VERSION        94400  /**< Current version, expressed as decimal Mmmbb, where (M) is the number before the decimal point, (mm) is the number after the decimal point, and (bb) is reserved */
 
 #ifndef DOXYGEN_AVOID_MUSCLE_MAINPAGE_TAG