"Fossies" - the Fresh Open Source Software Archive

Member "muscle/micromessage/README.TXT" (8 Jun 2019, 2645 Bytes) of package /linux/privat/muscle7.30.zip:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 This folder contains an extremely bare-bones C implementation of the 
    2 MUSCLE Message and MessageGateway APIs.
    3 
    4 If you want to avoid C++ in your program (usually because you want
    5 to minimize executable size, or because a C++ compiler is not available)
    6 you can use the MiniMessages APIs in the minimessage folder to 
    7 implement simple MUSCLE Message functionality instead.
    8 
    9 However, if even MiniMessage is too heavyweight, and you want an
   10 implementation that avoids dynamic memory allocation altogether,
   11 you can use this MicroMessage (aka "UMessage") implementation instead.
   12 
   13 This implementation never bothers to flatten or unflatten Message
   14 objects at all; instead it reads and writes flattened Message
   15 data directly from a raw buffer of bytes.
   16 
   17 That makes this implementation very efficient, but it does restrict
   18 its functionality.  In particular when constructing a MicroMessage
   19 buffer, data can only be appended.  Data already existing in the
   20 MicroMessage buffer is considered read-only.  Also, you can only
   21 add as much data as will fit into the byte-buffer you provided.
   22 Attempts to add more data than that will fail.
   23 
   24 These files do not depend on any other files outside of this folder,
   25 except for support/MuscleSupport.h.
   26 
   27 The MicroMessage.{c,h} files contain the MicroMessage API -- the
   28 equivalent to the MiniMessage class in the minimessage folder, or 
   29 the Message class in C++.  There are some significant
   30 differences between the two implementations, however:
   31 
   32 1) A UMessage object does not contain its own memory buffer --
   33    you must provide (and guarantee the lifetime of) your own
   34    external memory buffer that the UMessage object can
   35    read from and/or write to.
   36 
   37 2) Unlike the Message class, where fields in the Message are dynamically
   38    extensible, the UMessage API requires you to specify the number of
   39    items in a field in advance.  For example, to add three int32's to
   40    a C++ Message, you could do this:
   41 
   42      Message msg;
   43      msg.AddInt32("fieldname", 1);
   44      msg.AddInt32("fieldname", 2);
   45      msg.AddInt32("fieldname", 3);
   46      [...]
   47 
   48    Equivalent code using the UMessage API would look like this:
   49 
   50      char buf[1024];  // we assume our UMessage data will fit in 1024 bytes!
   51      UMessage msg;
   52      UMInitialize(&msg, buf, sizeof(buf));
   53 
   54      const int32 vals[3] = {1, 2, 3};
   55      UMAddInt32s(&msg, "fieldname", vals, 3);
   56      
   57    It's a bit less flexible, but it makes the implementation much
   58    simpler and more efficient.  If you're just adding a single
   59    value, it's a bit easier:
   60 
   61      UMAddInt32(&msg, "fieldname", 42);
   62 
   63    See the test file tests/testmicro.cpp for more example usages of the UMessage API.