15.3.475  src/lib/std/src/hostthread/cpu-bound-task-hostthreads.api

## cpu-bound-task-hostthreads.api
#
# Server hostthreads to offload cpu-intensive computations
# from the main threadkit hostthread.
#
# Any number of cycleservers can be started.
# Typically you'll want to start one cycleserver
# for each core on the host, or perhaps one less
# for better interactive response (to keep one core
# free for the main threadkit hostthread).
#
# For load balancing, the cycleservers take tasks
# from a single internal taskqueue on a first-come
# first-served basis
#
# See also:
#
#     src/lib/std/src/hostthread/io-bound-task-hostthreads.api
#     src/lib/std/src/hostthread/io-wait-hostthread.api

# Compiled by:
#     src/lib/std/standard.lib


stipulate
    package hth =  hostthread;                                                  # hostthread                    is from   src/lib/std/src/hostthread.pkg
herein

    # This api is implemented in:
    #
    #     src/lib/std/src/hostthread/cpu-bound-task-hostthreads.pkg

    api Cpu_Bound_Task_Hostthreads {
        #
        get_count_of_live_hostthreads: Void -> Int;                             # You'll typically want this to be equal to the number of cores, or one less.
        #
        change_number_of_server_hostthreads_to: String -> Int -> Void;          # Used both to run server hostthreads at system startup and also to stop them at system shutdown.
                                                                                # 'String' identifies caller;  used only to for logging.

#       start_one_server_hostthread:      String -> Void;                               # 'String' will be logged as the client requesting startup.
        #                                                                       # Returns number of cycleservers now running -- count includes the just-started one.

#       Do_Stop = { per_who:    String,                                         # 'per_who' will be logged as the client requesting shutdown.
#                   reply:      Void -> Void
#                 };
#        stop_one_server_hostthread:     Do_Stop -> Void;

        Do_Echo = { what:  String,                                              # 'what' will be passed to 'reply'.
                    reply: String -> Void                                       # This is mainly just for unit testing and such.
                  };
        echo:  Do_Echo -> Void;

        do:    (Void -> Void) -> Void;                                          # This is the workhorse call. Arg is thunk to evaluate -- any reply needed will be embedded within it.
                                                                                # NB: It is ESSENTIAL that the client thunk trap any exceptions it generates!

        is_doing_useful_work:   Void -> Bool;
            #
            # This is support for
            #
            #     no_runnable_threads_left__fate
            # from
            #    src/lib/src/lib/thread-kit/src/glue/threadkit-base-for-os-g.pkg
            #
            # which is tasked with exit()ing if the system is
            # deadlocked -- which is to say, no thread ready
            # to run and provably no prospect of ever having
            # a thread ready to run.
            #
            # If we have any hostthread currently processing a request
            # then it may in due course generate a reply waking up
            # a thread, so the system is not provably deadlocked and
            # no_runnable_threads_left__fate() should not exit.
    };
end;

## Code by Jeff Prothero: Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.