15.3.381  src/lib/src/lib/thread-kit/src/core-thread-kit/binarytree-ximp.api

## binarytree-ximp.api
#
# This file is intended purely for clone-and-mutate
# construction of new X imps ("ximps").
#
# For the big picture see the imp dataflow diagrams in
#
#     src/lib/x-kit/xclient/src/window/xclient-ximps.pkg
#
# Use protocol is:
#
#   {   (make_run_gun  ())   ->   { run_gun', fire_run_gun };
#       (make_end_gun ())   ->   { end_gun', fire_end_gun };
#
#       bxstate =  bx::make_binarytree_ximp_state ();
#       bxports =  bx::make_binarytree_ximp "Some name";
#       bx      =  bx_ports.clientport;                                                         # The clientport represents the imp for most purposes.
#
#       ...                                                                                     # Create other app imps.
#
#       bx::configure_binarytree_imp (bxports.configstate, bx_state, { ... }, run_gun' );       # Wire imp to other imps.
#                                                                                               # All imps will start when run_gun' fires.
#
#       ...                                                                                     # Wire up other app imps similarly.
#
#       fire_run_gun ();                                                                        # Start all app imps running.
#
#       bx::do_something (bx, 12);                                                              # Many calls like this over lifetime of imp.
#
#       ...                                                                                     # Similar calls to other app imps.
#
#       fire_end_gun ();                                                                        # Shut the imp down cleanly.
#   };
#
# The point of factoring off   make_binarytree_ximp_state()
# is to support creating a spec datastructure holding
# everything needed to create or recreate a running
# microthread graph, retaining the ability to shut it
# down, modify the spec, and then start up the modified
# graph, without losing any state.  (Think interactive
# editing of a GUI, say.)
#     To this end, the Binarytree_Ximp_State value should
# contain mutable values directly updated by the ximp,
# rather than being used merely to initialize values
# thereafter modified internally by the ximp.

# Compiled by:
#     src/lib/test/unit-tests.lib



stipulate
    include package   threadkit;                                                                # threadkit                             is from   src/lib/src/lib/thread-kit/src/core-thread-kit/threadkit.pkg
    #
    package btp =  binarytree_port;                                                             # binarytree_port                       is from   src/lib/src/lib/thread-kit/src/core-thread-kit/binarytree-port.pkg
herein

    # This api is implemented in:
    #
    #     src/lib/src/lib/thread-kit/src/core-thread-kit/binarytree-ximp.pkg
    #
    api Binarytree_Ximp
    {
        Exports = {                                                                             # Ports we provide for use by other imps.
                    binarytree_port:     btp::Binarytree_Port
                  };

        Imports = {                                                                             # Ports we provide for use by other imps.
                     leftkid:   Null_Or( btp::Binarytree_Port ),
                     rightkid:  Null_Or( btp::Binarytree_Port )
                   };

        Option = MICROTHREAD_NAME String;                                                       # 

        Binarytree_Egg =  Void -> (Exports,   (Imports, Run_Gun, End_Gun) -> Void);

        make_binarytree_egg:   (Int, List(Option)) -> Binarytree_Egg;                           # 
    };                                                                                          # api Binarytree_Ximp
end;