SYNOPSIS
#include <sys/debug_info.h>
mixed debug_info(int flag)
mixed debug_info(int flag, mixed arg)
mixed debug_info(int flag, mixed arg2, mixed arg3)
DESCRIPTION
Gather some driver internal debug information according
to the setting of flag:
DINFO_OBJECT (0): Information like heart_beat, enable_commands
etc. of the specified object will be printed, and 0 returned.
DINFO_MEMORY (1): Memory usage information like how many strings,
variables, inherited files, object size etc. will be printed
about the specified object, and 0 returned.
DINFO_OBJLIST (2): Objects from the global object list are
returned. If the optional second arg is omitted, the first
element (numbered 0) is returned. If the second arg is a
number n, the n'th element of the object list returned. If the
second arg is an object, it's successor in the object list is
returned. If the optional <arg2> is omitted, the first
element(s) (numbered 0) is returned. If the <arg2> is a
number n, the n'th element(s) of the object list returned. If the
<arg2> is an object, it's successor(s) in the object list is
The optional <arg3> specifies the maximum number of objects
returned. If it's 0, a single object is returned. If it is
a positive number m, an array with at max 'm' objects is
returned. This way, by passing __INT_MAX__ as <arg3> it is
possible to create an array of all objects in the game
(given a suitable maximum array size).
DINFO_MALLOC (3): Equivalent to typing ``malloc'' at the command
line. No second arg must be given. Returns 0.
DINFO_STATUS (4): Collect the status information of the driver.
The optional second arg can be 0, "tables", "swap", "malloc",
"malloc extstats" or any other argument accepted by the actual
driver. The result is a printable string with the status
information, or 0 if an invalid argument was given.
DINFO_DUMP (5): Dump the information specified by <arg2> into the
filename specified by <arg3>. If <arg3> is omitted, a default
file name is used. The function calls master->valid_write() to
check that it can write the files. The file in question is
always written anew.
Result is 1 on success, or 0 if an error occured.
<arg2> == "objects": dump information about all live objects.
Default filename is '/OBJ_DUMP', the valid_write() will read
'objdump' for the function.
For every object, a line is written into the file with the
following information in the given order:
- object name
- size in memory, shared data counted only once
- size in memory if data wouldn't be shared
- number of references
- 'HB' if the object has a heartbeat, nothing if not.
- the name of the environment, or '--' if the object has no
environment
- in parentheses the number of execution ticks spent in this
object
- the swap status:
nothing if not swapped,
'PROG SWAPPED' if only the program is swapped
'VAR SWAPPED' if only the variabes are swapped
'SWAPPED' if both program and variables are swapped
- the time the object was created
<arg2> == "destructed": dump information about all destructed
objects. Default filename is '/DEST_OBJ_DUMP', the
valid_write() will read 'objdump' for the function.
For every object, a line is written into the file with the
following information in the given order:
- object name
- number of references
- 'NEW' if the object was destructed in this executiong
thread, nothing if it is older already.
<arg2> == "opcodes": dump usage information about the opcodes.
Default filename is '/OPC_DUMP', the valid_write() will read
'opcdump' for the function.
<arg2> == "memory": dump a list of all allocated memory
blocks (if the allocator supports this).
Default filename is '/MEMORY_DUMP', the valid_write()
will read 'memdump' for the function, and the new data
will be appended to the end of the file.
If the allocator doesn't support memory dumps, this call will
always return 0, and nothing will be written.
This works best if the allocator is compiled with
MALLOC_TRACE and/or MALLOC_LPC_TRACE.
NOTE: Make sure that this option can't be abused!
DINFO_DATA (6): Return raw information about an aspect of
the driver specified by <arg2>. The result of the function
is an array with the information, or 0 for unsupported values
of <arg2>.
If <arg3> is given and in the range of array indices
for the given <arg2>, the result will be just the indexed array
entry, but not the full array.
Allowed values for <arg2> are: DID_STATUS, DID_SWAP, DID_MALLOC.
<arg2> == DID_STATUS (0): Returns the "status" and "status tables"
information. Following indices are defined:
int DID_ST_BOOT_TIME
The time() when the mud was started.
int DID_ST_ACTIONS
int DID_ST_ACTIONS_SIZE
Number and size of allocated actions.
int DID_ST_SHADOWS
int DID_ST_SHADOWS_SIZE
Number and size of allocated shadows.
int DID_ST_OBJECTS
int DID_ST_OBJECTS_SIZE
Total number and size of objects.
int DID_ST_OBJECTS_SWAPPED
int DID_ST_OBJECTS_SWAP_SIZE
Number and size of swapped-out object variable blocks.
int DID_ST_OBJECTS_LIST
Number of objects in the object list.
int DID_ST_OBJECTS_NEWLY_DEST
Number of newly destructed objects (ie. objects destructed
in this execution thread).
int DID_ST_OBJECTS_DESTRUCTED
Number of destructed but still referenced objects, not
counting the DID_ST_OBJECTS_NEWLY_DEST.
int DID_ST_OBJECTS_PROCESSED
Number of listed objects processed in the last backend
cycle.
float DID_ST_OBJECTS_AVG_PROC
Average number of objects processed each cycle, expressed
as percentage (0..1.0).
int DID_ST_OTABLE
Number of objects listed in the object table.
int DID_ST_OTABLE_SLOTS
Number of hash slots provided by the object table.
int DID_ST_OTABLE_SIZE
Size occupied by the object table.
int DID_ST_HBEAT_OBJS
Number of objects with a heartbeat.
int DID_ST_HBEAT_CALLS
Number of active heart_beat cycles executed so far
(ie. cycles in which at least one heart_beat() function
was called).
int DID_ST_HBEAT_CALLS_TOTAL
Total number of heart_beats cycles so far.
int DID_ST_HBEAT_SLOTS
int DID_ST_HBEAT_SIZE
Number of allocated entries in the heart_beat table
and its size.
int DID_ST_HBEAT_PROCESSED
Number of heart_beats called in the last backend cycle.
float DID_ST_HBEAT_AVG_PROC
Average number of heart_beats called each cycle, expressed
as fraction (0..1.0).
int DID_ST_CALLOUTS
int DID_ST_CALLOUT_SIZE
Number and total size of pending call_outs.
int DID_ST_ARRAYS
int DID_ST_ARRAYS_SIZE
Number and size of all arrays.
int DID_ST_MAPPINGS
int DID_ST_MAPPINGS_SIZE
Number and size of all mappings.
int DID_ST_HYBRID_MAPPINGS
int DID_ST_HASH_MAPPINGS
Number of hybrid (hash+condensed) and hash mappings.
int DID_ST_STRUCTS
int DID_ST_STRUCTS_SIZE
Number and size of all struct instances.
int DID_ST_STRUCT_TYPES
int DID_ST_STRUCT_TYPES_SIZE
Number and size of all struct type instances.
int DID_ST_PROGS
int DID_ST_PROGS_SIZE
Number and size of all programs.
int DID_ST_PROGS_SWAPPED
int DID_ST_PROGS_SWAP_SIZE
Number and size of swapped-out programs.
int DID_ST_USER_RESERVE
int DID_ST_MASTER_RESERVE
int DID_ST_SYSTEM_RESERVE
Current sizes of the three memory reserves.
int DID_ST_ADD_MESSAGE
int DID_ST_PACKETS
int DID_ST_PACKET_SIZE
Number of calls to add_message(), number and total size
of sent packets.
If the driver is not compiled with COMM_STAT, all three
values are returned as -1.
int DID_ST_PACKETS_IN
int DID_ST_PACKET_SIZE_IN
Number and total size of received packets.
If the driver is not compiled with COMM_STAT, all three
values are returned as -1.
int DID_ST_APPLY
int DID_ST_APPLY_HITS
Number of calls to apply_low(), and how many of these
were cache hits.
If the driver is not compiled with APPLY_CACHE_STAT, all two
values are returned as -1.
int DID_ST_STRINGS
int DID_ST_STRING_SIZE
Total number and size of string requests.
int DID_ST_STR_TABLE_SIZE
Size of the string table structure itself.
int DID_ST_STR_OVERHEAD
Size of the overhead per string.
int DID_ST_UNTABLED
int DID_ST_UNTABLED_SIZE
Total number and size of existing untabled strings.
int DID_ST_TABLED
int DID_ST_TABLED_SIZE
Total number and size of existing directly tabled strings.
int DID_ST_STR_CHAINS
Number of hash chains in the string table.
int DID_ST_STR_ADDED
Number of distinct strings added to the table so far.
int DID_ST_STR_DELETED
Number of distinct strings removed from the table so far.
int DID_ST_STR_COLLISIONS
Number of distinct strings added to an existing hash chain
so far.
int DID_ST_STR_SEARCHES
int DID_ST_STR_SEARCHLEN
Number and accumulated length of string searches by address.
int DID_ST_STR_SEARCHES_BYVALUE
int DID_ST_STR_SEARCHLEN_BYVALUE
Number and accumulated length of string searches by value.
int DID_ST_STR_FOUND
int DID_ST_STR_FOUND_BYVALUE
Number of successful searches by address resp. by value.
int DID_ST_RX_CACHED
Number of regular expressions cached.
int DID_ST_RX_TABLE
int DID_ST_RX_TABLE_SIZE
Number of slots in the regexp cache table, and size of the
memory currently held by it and the cached expressions.
int DID_ST_RX_REQUESTS
Number of requests for new regexps.
int DID_ST_RX_REQ_FOUND
Number of requested regexps found in the table.
int DID_ST_RX_REQ_COLL
Number of requested new regexps which collided with
a cached one.
int DID_ST_MB_FILE
The size of the 'File' memory buffer.
int DID_ST_MB_SWAP
The size of the 'Swap' memory buffer.
<arg2> == DID_SWAP (1): Returns the "status swap" information:
int DID_SW_PROGS
int DID_SW_PROG_SIZE
Number and size of swapped-out program blocks.
int DID_SW_PROG_UNSWAPPED
int DID_SW_PROG_U_SIZE
Number and size of unswapped program blocks.
int DID_SW_VARS
int DID_SW_VAR_SIZE
Number and size of swapped-out variable blocks.
int DID_SW_FREE
int DID_SW_FREE_SIZE
Number and size of free blocks in the swap file.
int DID_SW_FILE_SIZE
Size of the swap file.
int DID_SW_REUSED
Total reused space in the swap file.
int DID_SW_SEARCHES
int DID_SW_SEARCH_LEN
Number and total length of searches for block to reuse
in the swap file.
int DID_SW_F_SEARCHES
int DID_SW_F_SEARCH_LEN
Number and total length of searches for a block to free.
int DID_SW_COMPACT
TRUE if the swapper is running in compact mode.
int DID_SW_RECYCLE_FREE
TRUE if the swapper is currently recycling free block.
<arg2> == DID_MEMORY (2): Returns the "status malloc" information:
string DID_MEM_NAME
The name of the allocator: "sysmalloc", "smalloc",
"ptmalloc", "slaballoc"
int DID_MEM_SBRK (slaballoc, smalloc)
int DID_MEM_SBRK_SIZE (slaballoc, smalloc, ptmalloc)
Number and size of memory blocks requested from the
operating system (non-mmapped memory).
int DID_MEM_MMAP (ptmalloc)
int DID_MEM_MMAP_SIZE (ptmalloc)
Number and size of mmapped regions.
int DID_MEM_LARGE (slaballoc, smalloc)
int DID_MEM_LARGE_SIZE (slaballoc, smalloc)
int DID_MEM_LFREE (slaballoc, smalloc)
int DID_MEM_LFREE_SIZE (slaballoc, smalloc)
Number and size of large allocated resp. free blocks.
smalloc: The large allocated blocks include the
small chunk blocks.
int DID_MEM_LWASTED (slaballoc, smalloc)
int DID_MEM_LWASTED_SIZE (slaballoc, smalloc)
Number and size of unusable large memory fragments.
int DID_MEM_FREE_CHUNKS (ptmalloc)
Number of free chunks.
int DID_MEM_FFREE (ptmalloc)
int DID_MEM_FFREE_SIZE (ptmalloc)
Number of fastbin blocks, size of freed fastbin blocks.
int DID_MEM_CHUNK (smalloc)
int DID_MEM_CHUNK_SIZE (smalloc)
Number and size of small chunk blocks.
int DID_MEM_SLAB (slaballoc)
int DID_MEM_SLAB_SIZE (slaballoc)
Number and size of slabs (including fully free slabs).
int DID_MEM_SLAB_FREE (slaballoc)
int DID_MEM_SLAB_FREE_SIZE (slaballoc)
Number and size of free slabs (part of DID_MEM_SLAB).
int DID_MEM_SMALL (slaballoc, smalloc)
int DID_MEM_SMALL_SIZE (slaballoc, smalloc)
int DID_MEM_SFREE (slaballoc, smalloc)
int DID_MEM_SFREE_SIZE (slaballoc, smalloc)
Number and size of small allocated resp. free blocks.
int DID_MEM_SWASTED (smalloc)
int DID_MEM_SWASTED_SIZE (smalloc)
Number and size of unusably small memory fragments.
int DID_MEM_SMALL_OVERHEAD_SIZE (slaballoc)
Size of the slab management overhead (not including
the overhead incurred by each allocated small block).
int DID_MEM_MINC_CALLS (slaballoc, smalloc)
int DID_MEM_MINC_SUCCESS (slaballoc, smalloc)
int DID_MEM_MINC_SIZE (slaballoc, smalloc)
Number of calls to malloc_increment(), the number
of successes and the size of memory allocated this
way.
int DID_MEM_PERM (slaballoc, smalloc)
int DID_MEM_PERM_SIZE (slaballoc, smalloc)
Number and size of permanent (non-GCable) allocations.
int DID_MEM_CLIB (slaballoc, smalloc)
int DID_MEM_CLIB_SIZE (slaballoc, smalloc)
Number and size of allocations done through the
clib functions (if supported by the allocator).
int DID_MEM_OVERHEAD (slaballoc, smalloc, ptmalloc)
Overhead for every allocation.
int DID_MEM_ALLOCATED (slaballoc, smalloc, ptmalloc)
The amount of memory currently allocated from the
allocator, including the overhead for the allocator.
int DID_MEM_MAX_ALLOCATED (ptmalloc)
Maximum total allocated space.
int DID_MEM_USED (slaballoc, smalloc, ptmalloc)
The amount of memory currently used for driver data,
excluding the overhead from the allocator.
int DID_MEM_TOTAL_UNUSED (slaballoc, smalloc, ptmalloc)
The amount of memory allocated from the system, but
not used by the driver.
int DID_MEM_KEEP_COST (ptmalloc)
Top-most releasable space.
int DID_MEM_DEFRAG_CALLS (smalloc)
Total number of calls to defragment_small_lists().
int DID_MEM_DEFRAG_CALLS_REQ (smalloc)
Number of calls to defragment_small_lists() with a
desired size.
int DID_MEM_DEFRAG_REQ_SUCCESS (smalloc)
Number of times, a defragmentation for a desired
size was successful.
int DID_MEM_BLOCKS_INSPECTED (smalloc)
Number of blocks inspected during defragmentations.
int DID_MEM_BLOCKS_MERGED (smalloc)
Number of blocks merged during defragmentations.
int DID_MEM_BLOCKS_RESULT (smalloc)
Number of defragmented blocks (ie. merge results).
int DID_MEM_AVL_NODES (slaballoc, smalloc)
Number of AVL nodes used to manage the large free
blocks. This value might go away again.
mixed * DID_MEM_EXT_STATISTICS (slaballoc, smalloc)
If the driver was compiled with extended smalloc
statistics, they are returned in this entry; if the
driver was compiled without the statistics, 0 is
returned.
This value might go away again.
The array contains NUM+2 entries, where NUM is the
number of distinct small block sizes. Entry [NUM]
describes the statistics of oversized small blocks
(smalloc) resp. for all slabs (slaballoc),
entry [NUM+1] summarizes all large blocks. Each
entry is an array of these fields:
int DID_MEM_ES_MAX_ALLOC:
Max number of allocated blocks of this size.
int DID_MEM_ES_CUR_ALLOC:
Current number of allocated blocks of this size.
int DID_MEM_ES_MAX_FREE:
Max number of allocated blocks of this size.
int DID_MEM_ES_CUR_FREE:
Current number of allocated blocks of this size.
float DID_MEM_ES_AVG_XALLOC:
Number of explicit allocation requests per
second.
float DID_MEM_ES_AVG_XFREE:
Number of explicit deallocation requests per
second.
int DID_MEM_ES_FULL_SLABS:
Number of fully used slabs (slaballoc only).
int DID_MEM_ES_FREE_SLABS:
Number of fully free slabs (slaballoc only).
int DID_MEM_ES_TOTAL_SLABS:
Total number of slabs: partially used, fully used
and fully free (slaballoc only).
The allocation/deallocation-per-second statistics do
not cover internal shuffling of the freelists.
The slab statistics (entry [NUM], slaballoc only)
shows in the AVG statistics the frequence with which
slabs were allocated from resp. returned to the large
memory pool.
DINFO_TRACE (7): Return the call stack 'trace' information as specified
by <arg2>. The result of the function is either an array (format
explained below), or a printable string. Omitting <arg2> defaults
to DIT_CURRENT.
<arg2> == DIT_CURRENT (0): Current call trace
== DIT_ERROR (1): Most recent error call trace (caught
or uncaught)
== DIT_UNCAUGHT_ERROR (2): Most recent uncaught-error call
trace
Return the information in array form.
The error traces are changed only when an appropriate error
occurs; in addition a GC deletes them. After an uncaught
error, both error traces point to the same array (so the '=='
operator holds true).
If the array has more than one entries, the first entry is 0 or
the name of the object with the heartbeat which started the
current thread; all following entries describe the call stack
starting with the topmost function called.
All call entries are arrays themselves with the following
elements:
int[TRACE_TYPE]: The type of the call frame:
TRACE_TYPE_SYMBOL (0): a function symbol (shouldn't happen).
TRACE_TYPE_SEFUN (1): a simul-efun.
TRACE_TYPE_EFUN (2): an efun closure.
TRACE_TYPE_LAMBDA (3): a lambda closure.
TRACE_TYPE_LFUN (4): a normal lfun.
mixed[TRACE_NAME]: The 'name' of the called frame:
_TYPE_EFUN: either the name of the efun, or the code of
the instruction for operator closures
_TYPE_LAMBDA: the numeric lambda identifier.
_TYPE_LFUN: the name of the lfun.
string[TRACE_PROGRAM]: The (file)name of the program holding the
code.
string[TRACE_OBJECT]: The name of the object for which the code
was executed.
int[TRACE_LOC]:
_TYPE_LAMBDA: current program offset from the start of the
closure code.
_TYPE_LFUN: the line number.
<arg2> == DIT_STR_CURRENT (3): Return the information about the
current call trace as printable string.
<arg2> == DIT_CURRENT_DEPTH (4): Return the current number of
frames on the control stack (recursion depth).
DINFO_EVAL_NUMBER (8): Return the current evaluation number.
The number is incremented for each top-level call. Top-level
calls are initiated by the driver, usually in reaction to an
external event:
- commands (added by add_action)
- heart_beat, reset, clean_up
- calls from call_out or input_to
- master applies triggered by external events
- calls of driver hooks in reaction to external events
- send_erq callbacks
- logon in interactives
The number can be used to detect cases where the same code is
executed twice in the same top level evaluation (say, heart_beat),
and also for time stamps for ordering some events.
Please note that the counter may overflow, especially on 32 bit
systems. As a result, it can also be negative.
HISTORY
Since 3.2.7, DINFO_STATUS returns the status information instead
of printing it.
DINFO_DUMP introduced with 3.2.7.
LDMud 3.2.8 added the data size of the object to the result of
DINFO_MEMORY; the DINFO_DATA request; the DID_MEM_WASTED* stats.
LDMud 3.2.9 added DINFO_TRACE; the indexing feature for DINFO_DATA;
the 'destructed' DINFO_DUMP; the DID_MEM_CLIB*, DID_MEM_PERM*,
DID_ST_OBJECTS_NEWLY_DEST, DID_ST_OBJECTS_DEST, DID_MEM_OVERHEAD,
DID_MEM_ALLOCATED, DID_MEM_USED, DID_MEM_TOTAL_UNUSED, and
DID_ST_HBEAT_CALLS_TOTAL stats.
LDMud 3.2.10 added the object creation time to DINFO_DUMP:"objects",
removed DID_MEM_UNUSED from DINFO_DATA:DID_MEMORY; added
DID_ST_BOOT_TIME, DID_ST_MB_FILE and DID_ST_MB_SWAP to
DINFO_DATA:DID_STATUS; removed DID_ST_CALLOUT_SLOTS and from
DINFO_DATA:DID_STATUS; added the third argument to
DINFO_OBJLIST, and changed the meaning of
DID_ST_CALLOUT_SIZE and DID_ST_HBEAT_SIZE/_SLOTS.
LDMud 3.3 replaced the string related DID_ST_ constants according to
the new string implementation.
LDMud 3.3.387 added the ptmalloc values for DINFO_DATA:DID_MEMORY.
LDMud 3.3.479 added the DID_MEM_DEFRAG_ values
for DINFO_DATA:DID_MEMORY.
LDMud 3.3.526 added DINFO_DUMP:"memory".
LDMud 3.3.533 added DID_MEM_AVL_NODES for DINFO_DATA:DID_MEMORY.
LDMud 3.3.603 added DID_MEM_EXT_STATISTICS for
DINFO_DATA:DID_MEMORY.
LDMud 3.3.645 added DINFO_DATA:DID_ST_PACKETS_IN and
DID_ST_PACKET_SIZE_IN.
LDMud 3.3.679 removed DID_ST_IT_OVERHEAD and DID_ST_ITABLED*;
added DID_ST_HYBRID_MAPPINGS and DID_ST_HASH_MAPPINGS.
LDMud 3.3.718 added DIT_CURRENT_DEPTH to DINFO_TRACE.
LDMud 3.3.719 added DINFO_EVAL_NUMBER
SEE ALSO
trace(E), traceprefix(E), malloc(D), status(D), dumpallobj(D)
