15.3.516  src/lib/std/src/pthread/io-bound-task-pthreads.api

## io-bound-task-pthreads.api
#
# Server pthreads to offload I/O-intensive computations
# from the main threadkit pthread.
#
# Any number of servers pthreads can be started;
# for load balancing, these server pthreads take tasks
# from a single internal taskqueue on a first-come
# first-served basis
#
# The io-bound-task-pthreads api and implementation are
# identical to that of cpu-bound-task-pthreads;                                         # Cpu_Bound_Task_Pthreads               is from   src/lib/std/src/pthread/cpu-bound-task-pthreads.api
# the critical difference is that one wants only as many
# cpu-bound-task-pthreads as cores (more will just cause thrashing),
# but may reasonably have many more io-bound-task-pthreads,
# since in general they will simply sit blocked waiting for I/O.
#
# Do note however that currently each pthread costs 256KB,
# and that MAX_PTHREAD is currently hardwired at 32 in
#
#     src/c/mythryl-config.h
#
# See also:
#
#     src/lib/std/src/pthread/cpu-bound-task-pthreads.api
#     src/lib/std/src/pthread/io-wait-pthread.api

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


stipulate
    package pth =  pthread;                                                     # pthread                       is from   src/lib/std/src/pthread.pkg
herein

    # This api is implemented in:
    #
    #     src/lib/std/src/pthread/io-bound-task-pthreads.pkg

    api Io_Bound_Task_Pthreads {
        #
        get_count_of_running_pthreads: Void -> Int;                             # You'll typically want this to be equal to the number of cores, or one less.
        #
        start:      String -> Int;                                              # 'String' will be logged as the client requesting startup.
        #                                                                       # Returns number of lagservers now running -- count includes the just-started one.

        Do_Stop = { who:   String,                                              # 'who' will be logged as the client requesting shutdown.
                    reply: Void -> Void
                  };
        stop:     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.
    };
end;

## Code by Jeff Prothero: Copyright (c) 2010-2012,
## released under Gnu Public Licence version 3.