===== Pagoda Core Foundation (cf) library =====

This file describes in technical detail the functional differences between
released versions of the library.


===== Version 0.5 =====

Highlights of the changes:

+ Many bugs fixed (some critical).
+ IPv6 socket addresses are now a triple, containing the scope identifier.
+ Fixed a very bad stack leak problem in the [Cf_gadget] scheduler.

--- [Cf_deque]
    Fix major bug in [fold] that caused a BUS ERROR (ack!), and also fixed
    [filter] so that it uses the non-recursive [fold] function here instead of
    going to the extra work of using [Cf_seq.fold].

--- [Cf_rbtree]
    Fix a bug in [iterate] (found by Craig Falls; thanks Craig!) caused by a
    stoopid typo.  Caused some elements to be iterated twice, and others not
    at all.

--- [Cf_gadget]
    Moderate surgery on the scheduler to fix a bad stack leak.  The new code
    is probably a tiny bit more efficient too, because I got rid of some
    unnecessary uses of {Lazy.t} in places, and there is a bit less lifting
    between monads.  I didn't benchmark it, though.

--- [Cf_socket]
    Added a special case for Mac OS X to work around a bug in Apple's network
    stack that errors in connect(2) on a non-blocking socket do not get in
    the errno system variable.  You have to get them out of the socket with
    the SO_ERROR socket option.

--- [Cf_ip4_addr]
    Make the network subnet manipulation functions cope with networks that
    are not unicast networks.  (Yes, there are multicast ranges that can be
    treated like subnets.)

--- [Cf_ip6_proto]
    Add a third element to the socket address type: an int32 for the scope id.
    
--- [Cf_ip6_addr]
    Fix the [v4compat] and [v4mapped] address type tags so that they are
    actually polymorphic variants, like they're supposed to be.  This was
    another stoopid typo, but I found it myself.

--- [Cf_netif]
    Fixed the C-language code to call if_nametoindex() with the proper
    arguments.  Again, this was a stoopid typo.

--- [Cf_poll]
    A minor change to the commented bits of debugging code in the middle of the
    select loop to use [Cf_journal] instead of my [xprintf] hackery.

--- {TESTS}
    Added a test for the [Cf_gadget] scheduler to detect stack leaks.

===== Version 0.4 =====

Highlights of the changes:

+ Fix Makefile for architectures that do not support native compilers.
+ Fix major bug in the [Cf_gadget] scheduler that caused some wires to be
  prematurely collected without delivering events to their receivers.

--- [Cf_gadget]
    Fix major bug in the scheduler.  Events transmitted on wires that are no
    longer connected to a receiver are now delivered to any pending guards that
    were queued before the receiver was collected.  Minor changes to the
    debugging hints to use Cf_journal.

--- [Makefile]
    Samuel Mimram, the Debain maintainer of this package, says: There are some
    minor issues with your Makefile concerning non-native archs [...]:
    - the doc rule should use ocamldoc instead of ocamldoc.opt since it is
    not available on all archs (or add a optdoc rule);
    - the install rule should not depend on cf.cmxa and cf.a since they are
    not necessarly built.
    Thanks to Mr. Mimram for catching this.


===== Version 0.3 =====

Highlights of the changes:

+ Rewrite the scheduler in [Cf_gadget] so that it sucks less wind.  The kernel
  is now built entirely out of mutable structures, and we got rid of the 'pin'
  type because we don't represent wires internally as integer keys in a map.
+ Added [Cf_journal], a foundation for extensible diagnostic event journaling
  inspired by Log4j from the Apache Foundation.  (Look for a full suite of
  extensions to be sold separately.)
+ Removed the [?xf] optional exception function from the [Cf_lexer.create]
  function.  Use a derived cursor class with an [error] method that can be
  overridden for this purpose.
+ Added [Cf_scan_parser], which scans an input sequence using the [Scanf]
  module in the standard library.
+ Minor convenience functions added to [Cf_parser].
+ Other bug fixes.


--- [Cf_deque]
    Apply the iterative function in left-to-right order for all the utility
    functions.

--- [Cf_journal]
    All new functions.

--- [Cf_parser]
    Added the [filter], [map] and [optmap] functions for transforming parser
    with higher order functions on their output symbols.

--- [Cf_scan_parser]
    New module, allowing the mixing of [Scanf] and [Cf_lexer] in the same
    parser/lexer system.

--- [Cf_dfa, Cf_lexer]
    Added new ['i cursor] class.  Removed the ['c raise_exn_t] type and the
    [?xf] optional parameter from the [create] function.

--- [Cf_uri]
    Fixed bug in [refer_to_base] that allowed relative paths to resolve to
    absolute paths with a [".."] segment at the beginning of the path.  Also,
    changed to throw [Rel_undefined] instead of [Invalid_argument] (as the
    documentation specifies).
    Also, use the new [Cf_lexer.cursor] class, as now required.

--- [Cf_gadget]
    Major modifications for new scheduler.  The [pin_t] type is no longer.
    Should be more efficient (and less buggy).

--- [all *.c files]
    Stop abusing Field() as a lvalue in the C primitives.  The GC is reputed
    to hate that, and while we haven't encountered it in this library, we've
    seen it in others.  Best to be safe.

    Also: stop using CAMLlocalX() in subblocks of functions.  Just use them
    at the top of the main function block.  It seems to like that.

===== Version 0.2 =====

Highlights of the changes:

+ Major overhaul of [Cf_rbtree] to address serious performance issues (should
  improve performance of [Cf_dfa], [Cf_lexer], [Cf_poll] and [Cf_gadget]).
+ Defined [Cf_set.T] and [Cf_map.T] module types for use in abstracting the
  underlying algorithm behind sets and maps.
+ Added [Cf_seq.constrain] (and [Cf_seq.constrain2] for consistency).
+ Defined [Cf_heap.T] and [Cf_pqueue.T] module types for use in abstracting
  the use of skew-binomial heaps as either a heap or a priority queue.
  Reimplemented the interface to [Cf_sbheap] so it is consistent with the
  new [Cf_rbtree] interface.

--- [new files]
    Added [Cf_heap], [Cf_map], [Cf_pqueue] (and changed the meaning of the
    [Cf_set] module to be consistent).  These files all contain module types
    for common data structure algorithms implemented in the {Cf} library.
    Specific implementations are separated out into other modules.

--- [Cf_rbtree]
    Completely rewritten to address serious performance issues and to combine
    the interface for both sets and maps.  Use the new [Cf_rbtree.Set(K)] and
    [Cf_rbtree.Map(K)] functors.  Most functions now offer better performance
    for smoothly distributed input than do the [Set] and [Map] modules in the
    Ocaml standard library.  (Note: the [subset] function has been fixed so
    that it considers its arguments in the same order as the standard library.)

--- [Cf_sbheap]
    Minor modifications to conform to the new [Cf_heap] and [Cf_pqueue] module
    types.  Use the new [Cf_sbheap.Heap(K)] and [Cf_sbheap.PQueue(K)] functors.

--- [Cf_ordered]
    Removed the [KV_Pair_T] module type and its associated functor [KV_Pair],
    since these types are unecessary.

--- [Cf_seq]
    Added the [constrain] and [constrain2] functions for constraining a
    sequence to just those elements until the constraining function is false.

--- [Cf_dfa Cf_gadget Cf_poll]
    Modified to use the new [Cf_rbtree] and [Cf_sbheap] interface.

--- [t_cf]
    Added a new test case, that covers [Cf_flow.commute] and a few other
    things.  (Test coverage is still abyssmally poor, if you ask me.)

===== Version 0.1 =====

Highlights of the changes:

+ Compile and pass self-tests on Suse Linux 9.0.
+ Unified [sequence] and [accumulate] monad functions in [Cf_seq].
+ Added [Cf_exnopt] module with a simple convenience type.
+ New monadic constructors for [Cf_seq] and [Cf_flow] types.
+ Moderate overhaul of [Cf_gadget] (fix bugs, design problems).
+ Fix portability bugs in [Cf_socket] and cognates.
+ Add support for UDP, IP multicast and network interface selection.
+ Fix bug in [Cf_poll.idle] event polling (and give a timestamp).
+ Slightly better self-tests for [Cf_socket].

--- [Cf_cmonad, Cf_smonad, Cf_scmonad]
    Removed the [sequence] and [accumulate] functions.  Use the new functions
    in [Cf_seq] for this.

--- [Cf_exnopt]
    Added to library.  This is a simple sum type useful for defining monads
    that answer with either a value result or an Ocaml exception.

--- [Cf_seq]
    Added new functions for monadic construction.
    Use [writeC] to construct a sequence with a continuation monad.
    Use [writeSC] to construct a sequence with a state-continuation monad.
    Added new modules, [C] and [SC], containing the [sequence] and [accumulate]
    functions from [Cf_cmonad] and [Cf_scmonad] respectively.  (The functions
    from [Cf_smonad] have been removed completely.)

--- [Cf_flow]
    Added new function for monadic construction.
    Use [readC] and [writeC] to construct a flow with a continuation monad.
    Use [readSC] and [writeSC] to construct a flow with a state-continuation
    monad.
    Evaluating a continuation monad or a state-continuation monad with [evalC]
    or [evalSC] gives a resulting [('i, 'o) Cf_flow.t] value.

--- [Cf_gadget]
    In the [gate0_t] record, removed the [g_ptr_] field and changed the type
    of the [g_id_] field from an integer to a [pin_t] value.
    In the [kernel_t] record, changed the [k_rdyq_] field from a queue of
    [process0_t] values to a queue of [process0_t Lazy.t] values.
    Use [Cf_cmonad] by references, instead of by copy and paste.
    Define new class [Cf_gadget.connection] as the common base class of
    [Cf_gadget.rx] and [Cf_gadget.tx] to contain the [pin] method and two new
    methods: [check], which returns [false] if the other end of the connection
    has been collected by the garbage collector; and [id] which returns a text
    representation of the pin identifier (suitable for use in debug log
    messages).
    Removed [zguard] to replace with new [guard] and [rx] interface.  The new
    [rx#get] method returns a [guard_t] continuation monad which is evaluated
    by the new [guard method].  Internally, this is done by redefining [gate_t]
    as a continuation monad constructing a sequence of [gate0_t] values
    (parameterized by state).
    Optimized [tx#put] so that it does not enter the [scheduler_] function.
    Only [guard] can invoke a full pass through the scheduler now (though the
    scheduler could still use improvements for efficiency-- see ISSUES).
    Fixed an efficiency bug in [write] that unnecessarily constructed
    continuations.

--- [Cf_socket]
    Many platforms do not have a [sa_len] field in [sockaddr], so we now
    allocate socket address custom blocks with an extra [size_t] field at the
    beginning to carry the size of the structure.
    Stop using buffers of [SOCK_MAXADDRLEN] length and use the structure
    defined in RFC 3493 instead, i.e. [struct sockaddr_storage].
    Some socket options are not available on all platforms; therefore, allow
    the [opt_get] and [opt_set] fields in an option structure to be NULL if a
    platform doesn't support them.  The [getsockopt] and [setsockopt] function
    raise [Failure] when those socket options are used on those platforms.
    The [SO_REUSEPORT] and [SO_NOSIGPIPE] options are not available on Linux.

--- [Cf_nameinfo]
    Removed [ni_withscopeid] from list of flags.  This is a Mac OS X extension
    and I'm not sure how I will support address scoping issues yet.  Maybe it
    comes back later.
    Changes to handling of [sockaddr] structures to accommodate new
    representation required for [Cf_socket] functions.
    Stop using buffers of [SOCK_MAXADDRLEN] length and use the structure
    defined in RFC 3493 instead, i.e. [struct sockaddr_storage].

--- [Cf_netif]
    New module.  Provides wrapper around [if_nameindex] and cognates.

--- [Cf_ip4_addr, Cf_ip6_addr]
    Fixed several endianness bugs caused by failure to apply (or misapplication
    of) [ntohX] and [htonX] macros.
    Linux does not define [IN_LINKLOCAL], so we define it if it's undefined.
    Linux also does not define [IN6ADDR_NODELOCAL_ALLNODES_INIT],
    [IN6ADDR_LINKLOCAL_ALLNODES_INIT] or [IN6ADDR_LINKLOCAL_ALLROUTERS_INIT].
    Fix error in [cf_ip4_addr_compute_limits].

--- [Cf_ip_common, Cf_ip4_proto, Cf_ip6_proto]
    Add new protocol number for IPv6.
    Add [TCP_NODELAY] socket option.
    Add [Cf_ip4_proto.mreq_t] type for [IP_ADD/DROP_MEMBERSHIP] socket options.
    Add [Cf_ip6_proto.mreq_t] type for [IPV6_JOIN/LEAVE_GROUP] socket options.
    Add new socket options for IPv4 sockets: IP_TTL, IP_ADD_MEMBERSHIP,
    IP_DROP_MEMBERSHIP, IP_MULTICAST_IF, IP_MULTICAST_TTL and
    IP_MULTICAST_LOOP.
    Add new socket options for IPv6 sockets: IPV6_UNICAST_HOPS, IPV6_V6ONLY,
    IPV6_JOIN_GROUP, IPV6_LEAVE_GROUP, IPV6_MULTICAST_IF, IPV6_MULTICAST_HOPS,
    IPV6_MULTICAST_LOOP.
    Changes to handling of [sockaddr_in] and [sockaddr_in6] structures to
    accommodate new representation required for [Cf_socket] functions.
    Added a new primitive function [Cf_ip4_proto.siocgifaddr] that returns the
    interface address for a named interface.

--- [Cf_sock_common]
    Remove [send] and [recv] private methods from [Cf_sock_common.basic] class.

--- [Cf_sock_stream]
    Change [send] and [recv] methods on [Cf_sock_stream.endpoint] class from
    virtual override to simple concrete methods.
    Use an abbreviation module for [Cf_socket] in the implementation.

--- [Cf_sock_dgram]
    New module for SOCK_DGRAM sockets.

--- [Cf_udp4_socket, Cf_udp6_socket]
    New modules for UDP sockets (both IPv4 and IPv6).

--- [Cf_poll]
    Change [p_idle_queue_] field of [Cf_poll.t] record so that the callback
    function in each entry of the queue takes a [Cf_tai64n.t] timestamp
    indicating the timestamp when the idle condition arrived.
    Fix [cycle] so that idle polls are processed even when no other polls
    are loaded.


===== Version 0.0 =====

This was the initial release of the library.  Major and minor version numbers
count upward from zero.  Major version numbers with a minor version number of
zero indicate the first release in a "stable" branch.  Non-zero minor version
numbers indicate "development" branches converging on the next stable release.
Patches to stable releases are numbered with a third level of numbering.


--j h woodyatt <jhw@wetware.com>
