## heap-debug.api
#
# Heapcleaner ("garbage collector") control and statistics.
# Compiled by:
# src/lib/std/src/standard-core.sublib# This api is implemented in:
#
# src/lib/std/src/nj/heap-debug.pkg#
api Heap_Debug {
#
check_agegroup0_overrun_tripwire_buffer: String -> Void; # 'String' is caller, logged for diagnostic purposes if the check fails.
#
# Heisenbug-hunting assistance.
# Checks for allocation buffer overrun. If any word in
# the tripwire buffer is non-zero, logs buffer contents
# and exits.
# These two are used to control from the Mythryl level any extra
# logging compiled into the C runtime. Typically this is used when
# the logging statements would otherwise spam the logfile with
# gigabytes of unwanted spew. This is normally used only during
# debugging -- in a production system these calls will usually do nothing:
#
disable_debug_logging: Void -> Void; # Set global variable do_debug_logging to FALSE in src/c/lib/heap/libmythryl-heap.c
enable_debug_logging: Void -> Void; # Set global variable do_debug_logging to TRUE in src/c/lib/heap/libmythryl-heap.c
dump_all: String -> Void; # Dump to a file everything dumped by the other dump commands excepting dump_whatever().
dump_all_but_hugechunks_contents: String -> Void; # As above, except does not include output corresponding to dump_hugechunks_contents stuff.
dump_gen0: String -> Void; # Dump to a file the contents of the current Task's heap generation zero (allocation buffer) -- see src/c/h/heap.h
dump_gen0s: String -> Void; # Dump to a file the contents of all Task's heap generation zero (allocation buffer) -- see src/c/h/heap.h
dump_gen0_tripwire_buffers: String -> Void; # Dump to a file the contents of all Task's heap generation zero allocation buffer overrun tripwire buffers -- see src/c/h/heap.h
dump_gens: String -> Void; # Dump to a file the contents of heap generations one to N (max active generation).
dump_hugechunks_contents: String -> Void; # Dump to a file the contents of the hugechunk datastructures. (Currently used only to hold code.)
dump_hugechunks_summary: String -> Void; # Dump to a file a summary of the hugechunk datastructures. (Currently used only to hold code.)
dump_syscall_log: String -> Void; # Dump to a file the contents of the syscall_log circular queue from src/c/h/runtime-base.h
dump_task: String -> Void; # Dump to a file the contents of the current Task -- see struct task in src/c/h/runtime-base.h
dump_whatever: String -> Void; # Used for ad hoc debugging; in standard production codebase does nothing interesting.
#
# These dump various Mythryl-heap datastructures to
# disk in human-readable ascii-text form.
#
# The autogenerated filenames look like
#
# gen0dump-00006c5e-b4b1a730-1324722008.430408-0.log # The filename fields are: processid-hostthreadid-secondspartofdate-microsecondspartofdate-serialnumber.
# gensdump-00006c5e-b4b1a730-1324722008.454121-1.log
#
# The filenames are logged to the the current logfile (if any). # To set/open a logfile do: file::set_logger_to (log::log_TO_FILE "foo.log");
# The 'String' arg in each call is the caller, logged for
# diagnostic purposes.
breakpoint_0: Void -> Void;
breakpoint_1: Void -> Void;
breakpoint_2: Void -> Void;
breakpoint_3: Void -> Void;
breakpoint_4: Void -> Void;
breakpoint_5: Void -> Void;
breakpoint_6: Void -> Void;
breakpoint_7: Void -> Void;
breakpoint_8: Void -> Void;
breakpoint_9: Void -> Void;
#
# These are partial support for limited an clumsy but serviceable use
# of gdb (the GNU debugger) in conjunction with Mythryl scripts.
#
# This is intended mainly for debugging Mythryl library bindings which
# are segfaulting mysteriously. (At the moment, libmythryl-hostthread. :-)
#
#
# The idea here is to:
#
# 1) Fire up the Mythryl runtime
# mythryl-runtime-intel32
# from bin/ or /usr/bin/ under gdb.
#
# 2) Place gdb breakpoints on one or more of
# these breakpoint_*() fns.
#
# 3) In the Mythryl test script in question,
# insert calls to one or more of
# heap_debug::breakpoint_0();
# ...
# heap_debug::breakpoint_9();
# (These invoke the above breakpoint_*() C fns.)
# These will allow us to regain control of
# execution in gdb when script execution reaches
# that point.
#
# 4) Run the Mythryl compiler mythryld
# on the Mythryl test script in question.
#
# 5) Singlestep in gdb through the problematic code, or
# set more breakpoints in gdb or whatever.
#
# During major debug thrashes it may also pay to add actual C code to
# one or more of the above functions to interactively display stuff
# or to call problematic C code to allow convenient single-stepping
# through it or whatever.
write_line_to_log: String -> Void; # 'String' should end with a newline and contain no newlines or nuls.
#
# This is the primary debug-log facility; it typically logs to mythryl.log.
write_line_to_ramlog: String -> Void; # 'String' should end with a newline and contain no newlines or nuls.
#
# This is a facility to log strings into a circular buffer, where
# they can be displayed in gdb by doing debug_ramlog(<linecount>).
# This call is useful when logging events which happen so frequently
# that calling log::note would fill the disk or kill performance.
write_line_to_stderr: String -> Void; # 'String' should end with a newline and contain no newlines or nuls.
#
# This does a direct write(STDERR_FILENO, msg); bypassing all hostthread indirection etc.
# It is intended for debugging use only.
};
## Jeff Prothero Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.