9.60 release

jfriesne · Jan 19, 2025 · 61c9f92 · 61c9f92
1 parent 95e1d02
commit 61c9f92
Show file tree

Hide file tree

Showing 111 changed files with 824 additions and 726 deletions.
diff --git a/HISTORY.txt b/HISTORY.txt
@@ -5,6 +5,7 @@ key:  - new feature
       * bug fixed
       o other
 
+9.60 - Released 12/31/2024
    - Added a PreallocatedItemSlotsCount class to MuscleSupport.h
      which can be used to explicitly specify how many item-slots
      a container's constructor should preallocate space for.
@@ -45,6 +46,8 @@ key:  - new feature
    o Replaced CalculateChecksumForFloat() and CalculateChecksumForDouble()
      with a general/templatized CalculatePODChecksum() method.
    o Removed LogHexBytes() since PrintHexBytes() can now do the same thing.
+   o Updated the muscle-by-example programs to use an OutputPrinter in
+     their PrintExampleDescription( functions.
    * The deadlock finder no longer warns about inconsistent
      locking orders that consist entirely of shared/read-only locks.
    * The deadlock finder no longer considers TryLock() calls at

diff --git a/README.html b/README.html
@@ -2,7 +2,7 @@
 
 <H2>
 MUSCLE:  Crossbar Server, Portable Messaging and Support Classes<p>
-12/31/2024 v9.50 [email protected]<p>
+1/19/2025 v9.60 [email protected]<p>
 Jeremy Friesner / Meyer Sound Laboratories Inc.<p>
 Win32 compatibility contributions by Vitaliy Mikitchenko<p>
 C# client code by Wilson Yeung<p>

diff --git a/html/Beginners Guide.html b/html/Beginners Guide.html
@@ -1,7 +1,7 @@
 <HTML>
 <HEAD>
    <H1>MUSCLE Overview and Beginner's Guide</H1>
-   <H4>v9.50 / Jeremy Friesner / Meyer Sound Laboratories Inc ([email protected]) 12/31/2024</H4>
+   <H4>v9.60 / Jeremy Friesner / Meyer Sound Laboratories Inc ([email protected]) 1/19/2025</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>

diff --git a/html/Custom Servers.html b/html/Custom Servers.html
@@ -1,7 +1,7 @@
 <HTML>
 <HEAD>
    <H1>Implementing a Custom Server with MUSCLE</H1>
-   <H4>v9.50 / Jeremy Friesner / Meyer Sound Laboratories Inc ([email protected]) 12/31/2024</H4>
+   <H4>v9.60 / Jeremy Friesner / Meyer Sound Laboratories Inc ([email protected]) 1/19/2025</H4>
 </HEAD>
 <BODY bgcolor=#ffffff>
 <H2>Introduction</H2>

diff --git a/html/muscle-by-example/docs/outputprinter.md b/html/muscle-by-example/docs/outputprinter.md
@@ -0,0 +1,16 @@
+# muscle::OutputPrinter class [(API)](https://public.msli.com/lcs/muscle/html/classmuscle_1_1OutputPrinter.html)
+
+```#include "util/OutputPrinter.h"```
+
+[OutputPrinter](https://public.msli.com/lcs/muscle/html/classmuscle_1_1OutputPrinter.html) is a utility class for retargetting printf()-style text output to different destinations.
+
+* Code that otherwise would have called [printf() or fprintf()](https://man7.org/linux/man-pages/man3/fprintf.3.html) can call OutputPrinter::printf() instead.
+* By doing so, the code gains the ability to output to stdout, or stderr, or to any stdio FILE handle, or to a [String](https://public.msli.com/lcs/muscle/muscle/html/muscle-by-example/site/string/), or to the [MUSCLE Logging API](https://public.msli.com/lcs/muscle/muscle/html/muscle-by-example/site/logtime/), without further modifications.
+* OutputPrinter also supports automatic indentation of the generated text lines, for convenient visual nesting of hierarchical output.
+
+Try compiling and running the mini-example-programs in `muscle/html/muscle-by-example/examples/outputprinter` (enter `make` to compile example_*, and then run each from Terminal while looking at the corresponding .cpp file)
+
+Quick links to source code of relevant MUSCLE-by-example programs:
+
+* [outputprinter/example_1_basic_usage.cpp](https://public.msli.com/lcs/muscle/muscle/html/muscle-by-example/examples/outputprinter/example_1_basic_usage.cpp)
+* [outputprinter/example_2_indentation.cpp](https://public.msli.com/lcs/muscle/muscle/html/muscle-by-example/examples/outputprinter/example_2_indentation.cpp)
diff --git a/html/muscle-by-example/examples/CMakeLists.txt b/html/muscle-by-example/examples/CMakeLists.txt
@@ -72,6 +72,12 @@ if (WITH_EXAMPLES)
    add_executable(directory_example_1_basic_usage directory/example_1_basic_usage.cpp)
    target_link_libraries(directory_example_1_basic_usage muscle)
 
+   add_executable(outputprinter_example_1_basic_usage outputprinter/example_1_basic_usage.cpp)
+   target_link_libraries(outputprinter_example_1_basic_usage muscle)
+
+   add_executable(outputprinter_example_2_indentation outputprinter/example_2_indentation.cpp)
+   target_link_libraries(outputprinter_example_2_indentation muscle)
+
    add_executable(filepathinfo_example_1_basic_usage filepathinfo/example_1_basic_usage.cpp)
    target_link_libraries(filepathinfo_example_1_basic_usage muscle)
 

diff --git a/html/muscle-by-example/examples/atomiccounter/example_1_basic_usage.cpp b/html/muscle-by-example/examples/atomiccounter/example_1_basic_usage.cpp
@@ -3,24 +3,24 @@
 
 using namespace muscle;
 
-static void PrintExampleDescription()
+static void PrintExampleDescription(const OutputPrinter & p)
 {
-   printf("\n");
-   printf("This little program demonstrates basic usage of the muscle::AtomicCounter class.\n");
-   printf("\n");
-   printf("Note that this program calls AtomicCounter::GetCount() just to show what is going\n");
-   printf("on with the counter's value -- that's okay because this example uses only a single\n");
-   printf("thread, but in the more usual multi-threaded context, it's better to not call\n");
-   printf("AtomicCounter::GetCount() if you can avoid it, since the value you get back may\n");
-   printf("be obsolete (due to race conditions) by the time you examine it.\n");
-   printf("\n");
+   p.printf("\n");
+   p.printf("This little program demonstrates basic usage of the muscle::AtomicCounter class.\n");
+   p.printf("\n");
+   p.printf("Note that this program calls AtomicCounter::GetCount() just to show what is going\n");
+   p.printf("on with the counter's value -- that's okay because this example uses only a single\n");
+   p.printf("thread, but in the more usual multi-threaded context, it's better to not call\n");
+   p.printf("AtomicCounter::GetCount() if you can avoid it, since the value you get back may\n");
+   p.printf("be obsolete (due to race conditions) by the time you examine it.\n");
+   p.printf("\n");
 }
 
 int main(int argc, char ** argv)
 {
    CompleteSetupSystem css;
 
-   PrintExampleDescription();
+   PrintExampleDescription(stdout);
 
    AtomicCounter ac;
    printf("AtomicCounter's initial value is %i\n", ac.GetCount());

diff --git a/html/muscle-by-example/examples/atomiccounter/example_2_stress_test.cpp b/html/muscle-by-example/examples/atomiccounter/example_2_stress_test.cpp
@@ -4,15 +4,15 @@
 
 using namespace muscle;
 
-static void PrintExampleDescription()
+static void PrintExampleDescription(const OutputPrinter & p)
 {
-   printf("\n");
-   printf("This program stress-tests an AtomicCounter by having multiple threads\n");
-   printf("incrementing it and decrementing it simultaneously.\n");
-   printf("\n");
-   printf("After that, this program does the same thing with a plain-old-int\n");
-   printf("counter to demonstrate the difference in behavior.\n");
-   printf("\n");
+   p.printf("\n");
+   p.printf("This program stress-tests an AtomicCounter by having multiple threads\n");
+   p.printf("incrementing it and decrementing it simultaneously.\n");
+   p.printf("\n");
+   p.printf("After that, this program does the same thing with a plain-old-int\n");
+   p.printf("counter to demonstrate the difference in behavior.\n");
+   p.printf("\n");
 }
 
 // This will be modified by all threads without any synchronization (okay to do!)
@@ -77,7 +77,7 @@ int main(int argc, char ** argv)
 {
    CompleteSetupSystem css;
 
-   PrintExampleDescription();
+   PrintExampleDescription(stdout);
 
    const int NUM_THREADS = 10;
 

diff --git a/html/muscle-by-example/examples/bytebuffer/example_1_basic_usage.cpp b/html/muscle-by-example/examples/bytebuffer/example_1_basic_usage.cpp
@@ -3,19 +3,19 @@
 
 using namespace muscle;
 
-static void PrintExampleDescription()
+static void PrintExampleDescription(const OutputPrinter & p)
 {
-   printf("\n");
-   printf("This program demonstrates the basic usage of a ByteBuffer object to hold binary bytes\n");
-   printf("\n");
+   p.printf("\n");
+   p.printf("This program demonstrates the basic usage of a ByteBuffer object to hold binary bytes\n");
+   p.printf("\n");
 }
 
 /* This little program demonstrates basic usage of the muscle::ByteBuffer class */
 int main(int argc, char ** argv)
 {
    CompleteSetupSystem css;
 
-   PrintExampleDescription();
+   PrintExampleDescription(stdout);
 
    printf("Example ByteBuffer containing 64 bytes...\n");
 

diff --git a/html/muscle-by-example/examples/bytebuffer/example_2_bb_pool.cpp b/html/muscle-by-example/examples/bytebuffer/example_2_bb_pool.cpp
@@ -3,19 +3,19 @@
 
 using namespace muscle;
 
-static void PrintExampleDescription()
+static void PrintExampleDescription(const OutputPrinter & p)
 {
-   printf("\n");
-   printf("This program demonstrates getting a ByteBuffer from the ByteBuffer pool\n");
-   printf("\n");
+   p.printf("\n");
+   p.printf("This program demonstrates getting a ByteBuffer from the ByteBuffer pool\n");
+   p.printf("\n");
 }
 
 /* This little program demonstrates using the byte-buffers pool */
 int main(int argc, char ** argv)
 {
    CompleteSetupSystem css;
 
-   PrintExampleDescription();
+   PrintExampleDescription(stdout);
 
    // Grab a 128-byte ByteBuffer from the ByteBuffer pool
    ByteBufferRef bbRef = GetByteBufferFromPool(128);

diff --git a/html/muscle-by-example/examples/bytebuffer/example_3_endian.cpp b/html/muscle-by-example/examples/bytebuffer/example_3_endian.cpp
@@ -4,11 +4,11 @@
 
 using namespace muscle;
 
-static void PrintExampleDescription()
+static void PrintExampleDescription(const OutputPrinter & p)
 {
-   printf("\n");
-   printf("This example demonstrates adding big-endian numbers to a ByteBuffer using a CheckedBigEndianDataFlattener\n");
-   printf("\n");
+   p.printf("\n");
+   p.printf("This example demonstrates adding big-endian numbers to a ByteBuffer using a CheckedBigEndianDataFlattener\n");
+   p.printf("\n");
 }
 
 /* This program demonstrates the use of the CheckedBigEndianDataFlattener class
@@ -19,7 +19,7 @@ int main(int argc, char ** argv)
 {
    CompleteSetupSystem css;
 
-   PrintExampleDescription();
+   PrintExampleDescription(stdout);
 
    ByteBuffer buf;
 

diff --git a/html/muscle-by-example/examples/cpuloadmeter/example_1_basic_usage.cpp b/html/muscle-by-example/examples/cpuloadmeter/example_1_basic_usage.cpp
@@ -4,19 +4,19 @@
 
 using namespace muscle;
 
-static void PrintExampleDescription()
+static void PrintExampleDescription(const OutputPrinter & p)
 {
-   printf("\n");
-   printf("This example demonstrates using the CPULoadMeter class to measure the host computer's CPU usage percentage.\n");
-   printf("\n");
+   p.printf("\n");
+   p.printf("This example demonstrates using the CPULoadMeter class to measure the host computer's CPU usage percentage.\n");
+   p.printf("\n");
 }
 
 /* This little program demonstrates basic usage of the muscle::CPULoadMeter class */
 int main(int argc, char ** argv)
 {
    CompleteSetupSystem css;
 
-   PrintExampleDescription();
+   PrintExampleDescription(stdout);
 
    CPULoadMeter meter;
    while(true)

diff --git a/html/muscle-by-example/examples/dataio/example_1_basic_usage.cpp b/html/muscle-by-example/examples/dataio/example_1_basic_usage.cpp
@@ -4,18 +4,18 @@
 
 using namespace muscle;
 
-static void PrintExampleDescription()
+static void PrintExampleDescription(const OutputPrinter & p)
 {
-   printf("\n");
-   printf("This program demonstrates basic blocking-I/O usage of the muscle::DataIO interface\n");
-   printf("\n");
+   p.printf("\n");
+   p.printf("This program demonstrates basic blocking-I/O usage of the muscle::DataIO interface\n");
+   p.printf("\n");
 }
 
 int main(int argc, char ** argv)
 {
    CompleteSetupSystem css;
 
-   PrintExampleDescription();
+   PrintExampleDescription(stdout);
 
    printf("This program will accept input from stdin and write it to a file named example_1_dataio_output.txt.\n");
    printf("So go ahead and type whatever you want, and press CTRL-D when you are done.\n");

diff --git a/html/muscle-by-example/examples/dataio/example_2_tcp_server.cpp b/html/muscle-by-example/examples/dataio/example_2_tcp_server.cpp
@@ -6,26 +6,26 @@
 
 using namespace muscle;
 
-static void PrintExampleDescription()
+static void PrintExampleDescription(const OutputPrinter & p)
 {
-   printf("\n");
-   printf("This program demonstrates using DataIO objects to multiplex TCP connections with stdin input.\n");
-   printf("\n");
-   printf("The program will listen for incoming TCP connections on port 9999, and print any data they\n");
-   printf("send to us stdout.  It will also allow you to enter input on stdin, and anything you type will\n");
-   printf("be sent out to all connected TCP clients.\n");
-   printf("\n");
-   printf("Note that this program uses SocketMultiplexer (i.e. select()) to multiplex stdin with the\n");
-   printf("TCP socket I/O, which is supposed to be impossible under Windows.  StdinDataIO makes it\n");
-   printf("work under Windows anyway, via clever magic.\n");
-   printf("\n");
+   p.printf("\n");
+   p.printf("This program demonstrates using DataIO objects to multiplex TCP connections with stdin input.\n");
+   p.printf("\n");
+   p.printf("The program will listen for incoming TCP connections on port 9999, and print any data they\n");
+   p.printf("send to us stdout.  It will also allow you to enter input on stdin, and anything you type will\n");
+   p.printf("be sent out to all connected TCP clients.\n");
+   p.printf("\n");
+   p.printf("Note that this program uses SocketMultiplexer (i.e. select()) to multiplex stdin with the\n");
+   p.printf("TCP socket I/O, which is supposed to be impossible under Windows.  StdinDataIO makes it\n");
+   p.printf("work under Windows anyway, via clever magic.\n");
+   p.printf("\n");
 }
 
 int main(int argc, char ** argv)
 {
    CompleteSetupSystem css;
 
-   PrintExampleDescription();
+   PrintExampleDescription(stdout);
 
    const int tcpPort = 9999;
    ConstSocketRef acceptSock = CreateAcceptingSocket(tcpPort);

diff --git a/html/muscle-by-example/examples/dataio/example_3_seekable_dataio.cpp b/html/muscle-by-example/examples/dataio/example_3_seekable_dataio.cpp
@@ -3,18 +3,18 @@
 
 using namespace muscle;
 
-static void PrintExampleDescription()
+static void PrintExampleDescription(const OutputPrinter & p)
 {
-   printf("\n");
-   printf("This program demonstrates the use of a SeekableDataIO object (in particular, a FileDataIO) to write/seek/read in a file.\n");
-   printf("\n");
+   p.printf("\n");
+   p.printf("This program demonstrates the use of a SeekableDataIO object (in particular, a FileDataIO) to write/seek/read in a file.\n");
+   p.printf("\n");
 }
 
 int main(int argc, char ** argv)
 {
    CompleteSetupSystem css;
 
-   PrintExampleDescription();
+   PrintExampleDescription(stdout);
 
    FileDataIO fileDataIO(muscleFopen("example_3_seekable_dataio.txt", "w+"));  // "w+" lets us write, read, and update
    if (fileDataIO.GetFile() == NULL)

diff --git a/html/muscle-by-example/examples/dataio/example_4_idioms.cpp b/html/muscle-by-example/examples/dataio/example_4_idioms.cpp
@@ -4,18 +4,18 @@
 
 using namespace muscle;
 
-static void PrintExampleDescription()
+static void PrintExampleDescription(const OutputPrinter & p)
 {
-   printf("\n");
-   printf("This program demonstrates some handy idioms/tricks using the DataIO classes\n");
-   printf("\n");
+   p.printf("\n");
+   p.printf("This program demonstrates some handy idioms/tricks using the DataIO classes\n");
+   p.printf("\n");
 }
 
 int main(int argc, char ** argv)
 {
    CompleteSetupSystem css;
 
-   PrintExampleDescription();
+   PrintExampleDescription(stdout);
 
    printf("Read the entire contents of a file into a ByteBuffer, in two lines:\n");
    const char * inputFileName = "example_4_idioms.cpp";

diff --git a/html/muscle-by-example/examples/dataio/example_5_packet_dataio.cpp b/html/muscle-by-example/examples/dataio/example_5_packet_dataio.cpp
@@ -5,18 +5,18 @@
 
 using namespace muscle;
 
-static void PrintExampleDescription()
+static void PrintExampleDescription(const OutputPrinter & p)
 {
-   printf("\n");
-   printf("This program demonstrates blocking UDP I/O using the UDPSocketDataIO class.\n");
-   printf("\n");
+   p.printf("\n");
+   p.printf("This program demonstrates blocking UDP I/O using the UDPSocketDataIO class.\n");
+   p.printf("\n");
 }
 
 int main(int argc, char ** argv)
 {
    CompleteSetupSystem css;
 
-   PrintExampleDescription();
+   PrintExampleDescription(stdout);
 
    ConstSocketRef udpSock = CreateUDPSocket();
    if (udpSock() == NULL)