## io-bound-task-hostthreads.api
#
# Server hostthreads to offload I/O-intensive computations
# from the main threadkit hostthread.
#
# Any number of servers hostthreads can be started;
# for load balancing, these server hostthreads take tasks
# from a single internal taskqueue on a first-come
# first-served basis
#
# The io-bound-task-hostthreads api and implementation are
# identical to that of cpu-bound-task-hostthreads; # Cpu_Bound_Task_Hostthreads is from src/lib/std/src/hostthread/cpu-bound-task-hostthreads.api# the critical difference is that one wants only as many
# cpu-bound-task-hostthreads as cores (more will just cause thrashing),
# but may reasonably have many more io-bound-task-hostthreads,
# since in general they will simply sit blocked waiting for I/O.
#
# Do note however that currently each hostthread costs 256KB,
# and that MAX_HOSTTHREAD is currently hardwired at 32 in
#
# src/c/mythryl-config.h
#
# See also:
#
# src/lib/std/src/hostthread/cpu-bound-task-hostthreads.api# src/lib/std/src/hostthread/io-wait-hostthread.api# Compiled by:
# src/lib/std/standard.libstipulate
package hth = hostthread; # hostthread is from src/lib/std/src/hostthread.pkgherein
# This api is implemented in:
#
# src/lib/std/src/hostthread/io-bound-task-hostthreads.pkg api Io_Bound_Task_Hostthreads {
#
get_count_of_live_hostthreads: Void -> Int; # We currently set this to about the number of cores; the optimal policy is unclear.
#
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: 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 = { per_who: String, # 'per_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.
# 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.
# Debug crap: XXX SUCKO DELETEME
Do_Stop = { per_who: String, reply: Void -> Void };
Request = DO_STOP Do_Stop # Union of above record types, so that we can keep them all in one queue.
| DO_ECHO Do_Echo
| DO_TASK (Void -> Void)
;
mutex: hth::Mutex;
condvar: hth::Condvar;
external_request_queue: Ref(List(Request));
};
end;
## Code by Jeff Prothero: Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.