readme

这是一个著名的应用层组播中间件的源码

          MACEDON Release (1.2.1)

  What is MACEDON?

    MACEDON is a Methodology for Automatically Creating, Evaluating, and
    Designing Overlay Networks.  This distribution includes the source code
    for a code generator (compiler) called 'macedon', the source code needed
    to compile common library support for overlay networks, a sample random
    tree generator, and a test application.

  What are the hardware requirements?

    At this point -- MACEDON is being tested and developed on Debian Linux
    machines for GCC 3.x.  It should work equally well in other Linux
    environments, and we would like to know if it doesn't.  It may also be
    possible to port MACEDON to run in other *nix environments, or under
    CygWin/Windows, but this is not being actively done at this time.  We will
    update this file when/if we are aware of such a port.

  What's new since 1.2?

    The 1.2.1 release is mainly a bugfix release.  There are a few new features,
    but mainly performance and bugs.  Following are some specifics:

    - TCP Transport Fixes:
      o Connections are now indexed by vtime to reduce depedency on calls to 
        the current time.  Previously, calls which returned the same value
        could cause sockets to never get connected
      o Error signalling is now deferred if attempted from an "agent" thread.
        This is to preve
      o Sockets are not auto-reconnected when they break.  This is deferred
        until the next attempt to message the peer
      o The ModelNet hack has been fixed (to not cause problems when not running
        on ModelNet)
      o Thread cancellation has been corrected to interact properly with the 
        MACEDON scheduler code
    - Scribe's anycast code was buggy when anycast was called from the root of
      the anycast tree
    - Pastry has had numerous fixes, including handling node failures and some
      computational errors previously on modulo math.
    - neighbor_set worst functions now properly use DBL_MAX instead of a "really
      big number" for searching for the least neighbor delay.
    - Deprecated sockets have been removed from the code, MACEDON now correctly
      uses the port range specified in the params file
    - get_hostname has been modified not to use DNS, but instead just return 
      the ip address.  This is not a fix, so much as a performance workaround for
      systems with bad DNS systems.
    - If PROFILE_AGENTS is defined in the compiler, the agent code will be analyzed
      for call counts and time spent in the calls, like a basic profiling tool.
    - The compiler reports more errors where they occur in the .mac file, not
      in the generated code.
    - SplitStream is modified to use bitmap_digest rather than working_set.  When 
      working_set is compiled with USE_BLOOM (as it is by default), it produces
      some false positives which using bitmap_digest clears
    - Several other minor performance enhancements

  What's new since 1.1?
    
    There have been many stability updates since version 1.1.  Primary changes
    include a vastly improved TCP transport, release of the Chord and Overcast
    protocol specifications, fixes to the port binding bug, and a few new 
    features.

    Users may also notice the change from GCC 2.9x as default to GCC 3.x.  The 
    current code, while it should work with GCC 2.9x, has not been fully tested.

    - The TCP transport now signals errors which it observes so applications 
    can take appropriate actions.  These include READ errors, and are defined
    in tcp_auto_ext.h.  To get these errors, you can use the new 
    API transport_error block.
    - The TCP transport locking is now non-recursive, which may prevent
    problems down the road.
    - The TCP transport no longer drops messages when a criss-cross 
    (simultaneous connects from opposite sides) occurs.  (Though there
    is the chance presently for queued messages to seen out of order.
    - The TCP transport tracks the bw of the socket.  In the future a good API
    will exist to give that info to the agent.
    - The RW Locks for the agent have been disabled due to bugs.  (Non-RW locks
    are used instead)
    - The bitmap digest class is known to have bugs.
    - The SWP transport does not account for the RTT of the link, and never 
    gives up on retransmission.  It has been removed from current protocols,
    and will be removed in the future.  TCP and UDP the the only recommended
    protocols currently.  We are working on a replacement for SWP.
    - There is now a state hint which tells the higher protocol when the lower
    one is ready (see pastry and scribe for 'ready' and 'unready', and API
    status_change)
    - The compiler now supports automatic processing of some extensible calls.
    transport_error and status_change are examples.
    - Extra locking has been added to prevent some memory bugs when handling 
    fail-detect neighbors.
    - The multicast socket (not used) has been removed.
    - General tweaks and bugfixes (and things I have currently forgotten)
    

  What's new since 1.0?

    The biggest change is the inclusion of the first wave of MACEDON
    specifications to be made public.  This now includes bullet, pastry,
    scribe, and splitstream.  Otherwise, some minor changes have been made to
    the code structure and to the language.  For example, an optional queue
    length for transports may now be specified in the mac file.  Also --
    states may now be marked as "ready" or "unready," (the init state is
    "unready"), and when that status changes, the API status_changed is
    called.  Applications can also receive such notifications by registering
    an extensible upcall handler.  The command value is given in ext.h,
    and the argument is the status value, as specified in macedon_api.h.

    Additionally, note the following changes: 
    - the tar'd and gzip'd file now unpacks into a directory named 
      macedon-version-date 
    - a local ip address may now be passed in as the address to bind to. This
      should be used on multi-homed hosts, or when address detection fails.
    - The sockets will bind to the specified or detected IP, instead of 
      IPADDR_ANY.

  DOCUMENTATION:

    There is a version of the MACEDON manual included in this
    distribution as 'manual.pdf'  There are also several mailing lists
    at http://www.kcubes.com/cgi-bin/mailman/listinfo/ which can be used
    to find more information about the project.  In particular, there is
    a MACEDON-Users list for asking questions about how to use MACEDON or
    develop applications and tools with it.  There is also a MACEDON-Support
    list for getting help with the MACEDON source code, and discussing
    changes and bugfixes.  Finally, there is a MACEDON-Announce list for
    announcements of new versions or important changes pertaining to MACEDON.
    The authors can also be reached at [e-mail]

  GENERATING MACEDON Applications:

    There is a Makefile included in this distribution which can be used
    to build the compiler, compile the MACEDON libraries, compile MACEDON
    specifications, and to link the final executable.  The Makefile should
    be edited to suit the purposes of users.

    macedon.protocols: This file is used to assign protocol numbers to
    protocol specifications, and tells the Makefile to compile these
    protocols and create auxiliary structures for their use.

    Makefile: This is the main makefile.  Running 'make' will cause
    it to generate Makefile.proto, load_protocols.cc, Makefile.vars,
    and then to run make -f Makefile.proto and make -f Makefile.compile.
    Note that in the Makefile you can also specify a MODE, which tells the
    makefile whether to recompile the library or not.  Since the library
    is no longer being distributed in binary form, the default setting is
    to "hacker."  A setting of "user" will cause the library to be stable,
    and will just cause the Makefiles to recompile protocols and relink the
    test application.  The setting "macedonhacker" is for recompiling the
    'macedon' binary, and since that source code has not been released yet,
    we advise not using that mode.

    Makefile.vars: This makefile sets up a set of variables based on the
    protocols listed in macedon.protocols.  This Makefile is included in
    the others.

    Makefile.proto: This makefile handles compiling the specifications
    listed in macedon.protocols.  A specification is compiled by running
    './macedon <specification file>'

    load_protocols.cc: This file implements a function (load_protocols())
    which calls a static load function on each protocol, telling it what
    it's protocol number is, and allowing it to fill a global init_array
    function pointer array with a pointer to the protocol's init function,
    which returns an instance of the protocol agent.  These numbers are the
    ones listed in macedon.protocols.  Each protocol's static load_protocol
    function is declared in <protoname>2.h.

    Makefile.lib: This Makefile handles creation of the MACEDON library
    (libmacedon.a).  Note that it will only be included when the mode is 
    hacker or macedonhacker (set in the main Makefile)

    Makefile.compile: This makefile handles compilation of the application,
    and also additional library functions which are added in.  New libraries
    can be added either to the LIBS variable, their source to EXTRA_SRCS,
    or their object files to EXTRA_OBJS.  To change the target application,
    change the value of the PROGMACEDON variable.  Finally, if you are
    using GCC-3.x, uncomment the -DGCC3 in the CXXFLAGS variable.

    Makefile.gen: This Makefile handles building the MACEDON compiler.
    It is a Lexx/Yacc implementation, and is created from macedon.y,
    macedon.l, *.c, and macedon-conv-utils.h. Generally speaking, this 
    makefile need not be edited.

    When writing a new specification, you should add it to macedon.protocols
    with a new protocol number.  Then running Make will cause it to be
    compiled and linked into the test application.  We recommend using the
    test application as a base for applications built in this way, but it
    is not necessary. 

  MACEDON Protocols:

    As of the 1.2.0 release, there are 9 specifications included in the 
    release.  These are:

    randtree.mac: This simple multicast tree uses IP addressing, and 
      builds either a random tree, or a tree based on an initial 
      tree file.

    bullet.mac: This specification is consistent with the one used in the
      evaluation of the bullet SOSP 2003 paper, with some minor revisions
      for performance.

    The following protocols are MACEDON specifications of protocols which
    were not designed by the authors of MACEDON.  These have been written with
    the intention to be as faithful to their published work as possible, and
    have been discussed with their respective authors prior to inclusion in
    this MACEDON release.  But it should be noted that despite best efforts,
    some mistakes may have been made which were not the intention of the
    protocol authors.  When such discrepancies are noticed, please email
    [e-mail] to alert us to the problem.  Thanks.

    A special note about the Pastry/Scribe/SplitStream protocols: it seems
    that since their publishing, the Rice University and Microsoft Research
    designs of the algorithms have diverged slightly.  Therefore, we are
    supplying our specifications for both versions of the protocols as
    we understand them.  Also note that this version of Pastry does not
    yet diverge as it does not yet include changes from the most recent
    MS-Pastry tech report.

    pastry.mac: This specification is based on the original Pastry paper,
      with some additions from the proximity neighbor selection paper.

    scribe.mac: This specification is based on the original Scribe paper,
      with the addition of the anycast primitive, and with some modifications
      based on discussions with Rice University at SOSP 2003.

    splitstream.mac: This specification is based on the original SplitStream
      paper, with some modifications based on discussions with Rice University
      at SOSP 2003.

    scribems.mac: This specification is presently based on the original scribe
      work as published prior to SOSP 2003.  This version is described as
      the current version used by Microsoft Research.

    splitstreamms.mac: This specification is presently based on the
      original splitstream work as published at SOSP 2003.  This version
      is described as the current version used by Microsoft Research.

    overcast.mac: This specification is based on the original Overcast paper, 
      with some known differences noted in README.overcast.

    chord.mac: This specification is based on the original Chord paper, though 
      it has some limitations noted in README.chord.


  RUNNING THE TEST APPLICATION:

    This is addressed further in the manual.  The test application will be 
    generated as appmacedon, and includes functions to test single-source 
    multicast streaming.  The parameters are defined in manual.pdf.

  USING GCC-2.9x:

    To use GCC-2.9x with MACEDON, edit Makefile.compile, and comment -DGCC3.
    This causes some code variations based on this macro to conform to
    library changes from GCC-2.9x to GCC-3.xx.

  REPORTING PROBLEMS:

    To report problems with MACEDON or using MACEDON, or bugs, please email
    them to [e-mail]