@lpc-lang/core 1.1.2-5.1

package/src/efuns/fluffos/internals.h

@@ -0,0 +1,455 @@
+// internals.h
+
+/**
+ * traceprefix() - sets the prefix determining which objects to trace
+ *
+ * If  the  the traceprefix is set (i.e. not 0) tracing will only occur in
+ * objects having a name with the set prefix.
+ *
+ */
+string traceprefix( string prefix );
+
+/**
+ * trace() - sets trace flags and returns the old ones.
+ *
+ * Sets  the trace flags and returns the old trace flags.  When tracing is
+ * on a lot of information is printed during execution.
+ * 
+ * The trace bits are:
+ * 
+ * 1   Trace all function calls to lfuns.
+ * 
+ * 2   Trace all calls to "call_other".
+ * 
+ * 4   Trace all function returns.
+ * 
+ * 8   Print arguments at function calls and return values.
+ * 
+ * 16  Print all executed stack machine instructions (produces  a  lot  of
+ * output!).
+ * 
+ * 32  Enable trace in heart beat functions.
+ * 
+ * 64  Trace calls to apply.
+ * 
+ * 128 Show object name in tracing.
+ *
+ */
+int trace( int traceflags );
+
+/**
+ * time_expression()  -  return the amount of real time that an expression
+took
+ *
+ * Evaluate <expr>.  The amount of real time that passed during the evalu‐
+ * ation  of  <expr>,  in microseconds, is returned.  The precision of the
+ * value is not necessarily 1 microsecond; in fact, it  probably  is  much
+ * less precise.
+ *
+ */
+int time_expression( mixed expr );
+
+/**
+ * swap - swap out a file explicitly
+ *
+ * This  efun  should be reserved for debugging only.  It allows an object
+ * to be explicitly swapped out.  If enabled, it is  strongly  recommended
+ * that a simul_efun override (for this efun) be used to prevent abuse.
+ * 
+ * Note:  objects which have been destructed, already swapped out, contain
+ * a heart beat, cloned, inherited, or interactive, cannot be swapped out.
+ *
+ */
+void swap( object );
+
+/**
+ * set_malloc_mask()  -  sets the mask controlling display of malloc debug
+info
+ *
+ * This efun is only available when DEBUGMALLOC and DEBUGMALLOC_EXTENSIONS
+ * are  both defined in options.h at driver build time.  The mask controls
+ * what memory-related debugging information is displayed  as  the  driver
+ * allocates  and  deallocates memory.  Read md.c in the driver source for
+ * more information.
+ *
+ */
+void set_malloc_mask( int mask );
+
+/**
+ * set_debug_level()  -  sets the debug level used by the driver's debug()
+macro
+ *
+ * The purpose of this efun is to allow the amount and type of
+ * debugging information produced to be controlled from within the mud
+ * (while the driver is running).
+ * 
+ * The information is printed to stdout as well as to the file specified in
+ * the runtime configuration file as the "debug log file" setting.
+ * 
+ * The level is a bitmask integer or a string. If using an integer, multiple
+ * levels can be set by using the bitwise OR operator (|).
+ * 
+ * The following levels are available:
+ * "call_out"        1 << 0
+ * "d_flag"          1 << 2
+ * "connections"     1 << 3
+ * "mapping"         1 << 4
+ * "sockets"         1 << 5
+ * "comp_func_tab"   1 << 6
+ * "LPC"             1 << 7
+ * "LPC_line"        1 << 8
+ * "event"           1 << 9
+ * "dns"             1 << 10
+ * "file"            1 << 11
+ * "add_action"      1 << 12
+ * "telnet"          1 << 13
+ * "websocket"       1 << 14
+ * 
+ * When level is an integer, the debug level will be set to that value,
+ * erasing any previous settings.
+ * 
+ * If level is a string, the debug level for that option will be toggled on,
+ * while all other options will be preserved.
+ *
+ */
+void set_debug_level( int | string level );
+
+/**
+ * set_config() - set various driver config settings during runtime
+ *
+ * This efun is used to set the driver's various config settings during
+ * runtime. Please refer to the "runtime_config.h" include file for a list of
+ * currently recognized options.
+ * 
+ * Note that this only modifies the currently running options and will not
+ * persist across driver restarts.
+ *
+ * // set the driver's heartbeat to 1000 milliseconds
+ * set_config(__RC_HEARTBEAT_INTERVAL_MSEC__, 1000)
+ * 
+ * // adjust the driver's limit for call_out(0)
+ * set_config(__RC_CALL_OUT_ZERO_NEST_LEVEL__, 250)
+ *
+ */
+void set_config( int option, mixed value );
+
+/**
+ * rusage() - reports information gathered by the getrusage() system call
+ *
+ * This  efun  collects  information  gathered  via the getrusage() system
+ * call.  Read the getrusage() man  page  for  more  information  on  what
+ * information   will   be  collected.   Some  systems  do  not  have  the
+ * getrusage() system call but do have the times() system call.  On  those
+ * systems,  only  "utime"  and  "stime"  will  be  available.   Times are
+ * reported in milliseconds.
+ * 
+ * Here is an example usage of rusage():
+ * 
+ * void
+ * create()
+ * {
+ * mapping info;
+ * 
+ * info = rusage();
+ * write("user time = " + info["utime"] + "ms\n");
+ * write("system time = " + info["stime"] + "ms\n");
+ * }
+ * 
+ * The available fields are:
+ * 
+ * utime, stime, maxrss, ixrss, idrss, isrss, minflt,  majflt,  nswap,
+ * inblock, oublock, msgsnd, msgrcv, nsignals, nvcsw, nivcsw.
+ *
+ */
+mapping rusage( void );
+
+/**
+ * refs - return the number of references to a data structure
+ *
+ * The number of references to 'data' will be returned by refs().  This is
+ * useful for deciding whether or not to make a copy of a  data  structure
+ * before returning it.
+ *
+ */
+int refs( mixed data );
+
+/**
+ * query_load_average() - forces an error to occur in an object.
+ *
+ * This  function  returns a string which reports two things: 1) user com‐
+ * mands per second, and 2) compiled lines per second.
+ *
+ */
+string query_load_average( void );
+
+/**
+ * opcprof() - reports statistics on calling frequencies of various efuns
+ *
+ * This  function dumps a list of statistics on each efunction and eopera‐
+ * tor.  If no argument is specified, then the information will be  dumped
+ * to  files  named  /OPCPROF.efun  and /OPCPROF.eoper.  If an argument is
+ * specified, then that name is used as the filename for the dump.
+ *
+ */
+void opcprof( string | void );
+
+/**
+ * mud_status() - report various driver and mudlib statistics
+ *
+ * This  function  writes  driver  and  mudlib  statistics to the caller's
+ * screen.  If extra is non-zero,  then  additional  information  will  be
+ * written.   This  function  replaces  the hardcoded 'status' and 'status
+ * tables' commands in vanilla 3.1.2.
+ *
+ */
+void mud_status( int extra );
+
+/**
+ * moncontrol() - turns on/off profiling during execution
+ *
+ * If passed 1, moncontrol() enables profiling.  If passed 0, moncontrol()
+ * disables profiling.  It can be called many times during execution, typ‐
+ * ical use is to profile only certain parts of driver execution.  moncon‐
+ * trol() has no effect if profiling is  not  enabled  at  driver  compile
+ * time.
+ *
+ */
+void moncontrol( int on );
+
+/**
+ * memory_info - obtain info on object/overall memory usage
+ *
+ * If  optional argument 'ob' is given, memory_info() returns the approxi‐
+ * mate amount of memory that 'ob' is using.  If  no  argument  is  given,
+ * memory_info()  returns the approximate amount of memory that the entire
+ * mud is using.  Note that the amount of memory the mud is using does not
+ * necessarily  correspond  to  the amount of memory actually allocated by
+ * the mud from the system.
+ *
+ */
+varargs int memory_info( object ob );
+
+/**
+ * malloc_status() - report various statistics related to memory usage.
+ *
+ * This  function  writes  memory usage statistics to the caller's screen.
+ * This function replaces the hardcoded 'malloc' command in vanilla 3.1.2.
+ * Note  that  the  output  produced by malloc_status() depends upon which
+ * memory management package is chosen  in  options.h  when  building  the
+ * driver.
+ *
+ */
+void malloc_status( void );
+
+/**
+ * get_config() - query various driver config settings
+ *
+ * This efun is used to query the driver's various config settings.
+ * Please refer to the "runtime_config.h" include file for a list of currently
+ * recognized options.
+ *
+ * get_config( __RC_HEARTBEAT_INTERVAL_MSEC__ );
+ * get_config( __RC_CALL_OUT_ZERO_NEST_LEVEL__ );
+ *
+ */
+string | int get_config( int );
+
+/**
+ * dumpallobj()  - report various statistics on all objects that have been
+loaded
+ *
+ * This function dumps a list of statistics on all objects that have  been
+ * loaded.   If  no  argument  is  specified, then the information will be
+ * dumped to a file named /OBJ_DUMP.  If an argument  is  specified,  then
+ * that name is used as the filename for the dump.
+ *
+ */
+void dumpallobj( string | void );
+
+/**
+ * dump_socket_status() - display the status of each LPC socket
+ *
+ * dump_socket_status()  is  a diagnostic facility which displays the cur‐
+ * rent status of all LPC sockets configured into the MudOS driver.  It is
+ * useful  for debugging LPC sockets applications.  Each row in the output
+ * corresponds to a single LPC socket.  The first row corresponds  to  LPC
+ * socket descriptor 0, the second row, 1, etc.  The total number of sock‐
+ * ets is configured when the driver is built.
+ * 
+ * The first column "Fd" is the operating system file  descriptor  associ‐
+ * ated  with the LPC socket.  "State" is the current operational state of
+ * the LPC socket.  "Mode" is the socket mode, which is passed as an argu‐
+ * ment to socket_create().  The local and remote addresses are the Inter‐
+ * net address and port numbers in Internet dot notations.  '*'  indicates
+ * an  address  or  which  is  0.  N.B. LPC sockets that are in the CLOSED
+ * state are not currently in use; therefore the data displayed  for  that
+ * socket may be idiosyncratic.
+ * 
+ * The  following  output  was generated on Portals, where the only socket
+ * application running at the time was MWHOD.  It indicates that two sock‐
+ * ets  are  current in use, one is listening for connection requests on a
+ * STREAM mode socket.  The other is waiting for incoming data on a  DATA‐
+ * GRAM mode socket.
+ * 
+ * Fd    State      Mode      Local Address      Remote Address
+ * --  ---------  --------  -----------------  ------------------
+ * 13   LISTEN     STREAM   *.6889             *.*
+ * 14    BOUND    DATAGRAM  *.6888             *.*
+ * -1    CLOSED      MUD    *.*                *.*
+ *
+ */
+void dump_socket_status( void );
+
+/**
+ * dump_prog() - dump/disassemble an LPC object
+ *
+ * dump_prog()  dumps  information  about  the program of 'obj' to a file,
+ * 'file', or "/PROG_DUMP" if 'file' is not given.  If the current  object
+ * does not have write access to the file, it fails.
+ * 
+ * Flags  can be a combination of the following values: 1 - include a dis‐
+ * assembly of the i-code 2 - include line number information
+ *
+ * @param {object} ob - the object to dump
+ * @param {int} flags - the flags to use, defaults to 
+ * @param {string} file - the file to dump to, defaults to "/PROG_DUMP"
+ */
+varargs void dump_prog(object ob, int flags, string file);
+
+/**
+ * dump_file_descriptors() - dump the MudOS process file descriptor table
+ *
+ * This  function  is provided to assist in debugging the MudOS driver and
+ * helps overcome deficiencies in some UN*X implementations which  do  not
+ * provide  equivalent  or  superior  debugging  facilities as part of the
+ * operating system itself.  The interpretation of the output is very sys‐
+ * tem-dependent.  Each file descriptor is checked to determine whether it
+ * refers to an open file.  If so, information is displayed from the "stat
+ * structure" returned by the fstat() system call.
+ * 
+ * The following output was produced on Lambda Realms running on a Sequent
+ * DYNIX/ptx system:
+ * 
+ * Fd  Device Number  Inode   Mode    Uid    Gid      Size
+ * --  -------------  -----  ------  -----  -----  ----------
+ * 0     3      2    10319  c  666      0      3           0
+ * 1    79      7   164598  f  644   2862      1      789522
+ * 2    79      7   164598  f  644   2862      1      789522
+ * 3    40    33b     6925  c    0   2862      1           0
+ * 4    40    2a4     6943  c    0   2862      1           0
+ * 5    79      7   164599  f  600   2862      1       44784
+ * 6    40    2e2   145996  c    0   2862      1           0
+ * 7    79      7   164601  f  644   2862      1         506
+ *
+ */
+void dump_file_descriptors( void );
+
+/**
+ * debugmalloc() - dumps information on malloc'd memory to a file.
+ *
+ * This efun is only available when DEBUGMALLOC and DEBUGMALLOC_EXTENSIONS
+ * are both defined in options.h at driver build time.  The  debugmalloc()
+ * efun will dump information on those chunks of memory allocated by DMAL‐
+ * LOC() and related macros if the mask bitwise and'd  (&)  with  the  tag
+ * supplied  by  the macro (i.e. (mask & tag)) is non-zero.  Read md.c and
+ * config.h in the driver source for more information.
+ *
+ */
+void debugmalloc( string filename, int mask );
+
+/**
+ * debug_levels
+ *
+ * Returns a mapping of the current debug levels, where the keys are the
+ * names of the debug levels and the values 0 (disabled) or the integer
+ * value representing the bitmask value of the debug level.
+ *
+ * set_debug_level( (1 << 0) | (1 << 2) | (1 << 3) | (1 << 4) | (1 << 5) );
+ * printf("%O\n", debug_levels());
+ * 
+ * Result:
+ * ([ /* sizeof() == 14 *\/
+ * "telnet" : 0,
+ * "file" : 0,
+ * "LPC_line" : 0,
+ * "mapping" : 16,
+ * "d_flag" : 4,
+ * "add_action" : 0,
+ * "event" : 0,
+ * "comp_func_tab" : 0,
+ * "sockets" : 32,
+ * "dns" : 0,
+ * "websocket" : 0,
+ * "LPC" : 0,
+ * "connections" : 8,
+ * "call_out" : 1,
+ * ])
+ *
+ */
+mapping debug_levels();
+
+/**
+ * debug_info() - display debug information
+ *
+ * debug_info()  is  a general-purpose facility which may be used to debug
+ * the MudOS driver.  The debugging information requested is determined by
+ * the  first  argument.  Successive arguments are determine by the opera‐
+ * tion selected.
+ * 
+ * The existing operations (0 and 1) require a second  object  type  argu‐
+ * ment, and may be used to display the various fields of the MudOS object
+ * structure.
+ * 
+ * The following LPC code was used to generate the sample output:
+ * 
+ * /* di0.c *\/
+ * create() {
+ * debug_info(0, this_object());
+ * }
+ * 
+ * O_HEART_BEAT      : FALSE
+ * O_IS_WIZARD       : FALSE
+ * O_ENABLE_COMMANDS : FALSE
+ * O_CLONE           : FALSE
+ * O_DESTRUCTED      : FALSE
+ * O_SWAPPED         : FALSE
+ * O_ONCE_INTERACTIVE: FALSE
+ * O_RESET_STATE     : FALSE
+ * O_WILL_CLEAN_UP   : FALSE
+ * O_WILL_RESET: TRUE
+ * total light : 0
+ * next_reset  : 720300560
+ * time_of_ref : 720299416
+ * ref         : 2
+ * swap_num    : -1
+ * name        : 'u/c/cynosure/di0'
+ * next_all    : OBJ(bin/dev/_update)
+ * This object is the head of the object list.
+ * 
+ * /* di1.c *\/
+ * create() {
+ * debug_info(1, this_object());
+ * }
+ * 
+ * program ref's 1
+ * Name u/c/cynosure/di1.c
+ * program size 10
+ * num func's 1 (16)
+ * num strings 0
+ * num vars 0 (0)
+ * num inherits 0 (0)
+ * total size 104
+ *
+ */
+mixed debug_info( int operation... );
+
+/**
+ * cache_stats() - report various driver and mudlib statistics
+ *
+ * This  efun  is only available if CACHE_STATS is defined in options.h at
+ * driver build time.  This efun  dumps  statistics  on  the  call_other()
+ * cache hit rate to the caller's screen.
+ *
+ */
+void cache_stats( void );
+

package/src/efuns/fluffos/lpc-config.json

@@ -0,0 +1,10 @@
+{
+    "driver": {
+        "type": "fluffos"
+    },
+    "include": ["./"],
+    "compilerOptions": {
+        "noLib": true
+    },
+    "diagnostics": "off"
+}

package/src/efuns/fluffos/mappings.h

@@ -0,0 +1,205 @@
+// mappings.h
+
+/**
+ * values() - return an array of the values from the (key, value) pairs
+           in a mapping
+ *
+ * values() returns an array of values corresponding to the value elements
+ * in the (key, value) pairs stored in the mapping m.
+ * 
+ * For example, if:
+ * 
+ * mapping m;
+ * 
+ * m = (["hp" : 35, "sp" : 42, "mass" : 100]);
+ * 
+ * then
+ * 
+ * values(m) == ({35, 42, 100})
+ * 
+ * Note: the values will be returned in the same order as the  correspond‐
+ * ing keys.
+ *
+ */
+mixed *values( mapping m );
+
+/**
+ * unique_mapping() - create a mapping from an array based on a function
+ *
+ * Returns a mapping built in the following manner:
+ * 
+ * 'ob->fun()' or 'f' is evaluated for each member of the array.  The mem‐
+ * bers for  which  the  function  returns  the  same  value  are  grouped
+ * together, and associated with the return value as the key.
+ * 
+ * The  key/value  ordering  in the returned mapping is consistent but not
+ * guaranteed to not change in the future.
+ *
+ */
+mapping unique_mapping( mixed *arr, string fun, object ob,
+                          mixed extra... );
+mapping unique_mapping( mixed *arr, function f, mixed extra... );
+
+/**
+ * match_path() - search a mapping for a path
+ *
+ * match_path()  searches a mapping for a path.  Each key is assumed to be
+ * a string.  The value is  completely  arbitrary.   The  efun  finds  the
+ * largest matching path in the mapping.  Keys ended in '/' are assumed to
+ * match paths with character that follow the '/', i.e. /  is  a  wildcard
+ * for anything below this directory.
+ *
+ */
+mixed match_path( mapping m, string str );
+
+/**
+ * mapp() - determine whether or not a given variable is a mapping
+ *
+ * Return 1 if 'arg' is a mapping.
+ *
+ */
+int mapp( mixed arg );
+
+/**
+ * map_mapping()  -  modify  an  mapping  of elements via application of a
+function
+ *
+ * Returns an mapping with the same keys as  map  whose  items  have  been
+ * mapped  throught  'ob->fun()'  or 'f'.  The function is called for each
+ * element in 'map' and the return value is  put  back  in  that  spot  in
+ * 'map'.   'extra' and following are passed as parameters to the function
+ * after the item.
+ *
+ */
+mapping map_mapping( mapping map,
+                     string fun,
+                     object ob,
+                     mixed extra... );
+mapping map_mapping( mapping map, function f, mixed extra... );
+
+/**
+ * map_delete()  -  remove a (key, value) pair from a mapping based on the
+key
+ *
+ * map_delete removes the (key, value) from the mapping  m  that  has  key
+ * equal to element.
+ * 
+ * For example, given:
+ * 
+ * mapping names;
+ * 
+ * names = ([]);
+ * names["truilkan"] = "john";
+ * names["wayfarer"] = "erik";
+ * names["jacques"] = "dwayne";
+ * 
+ * Then:
+ * 
+ * map_delete(names,"truilkan");
+ * 
+ * causes the mapping 'names' to be equal to:
+ * 
+ * (["wayfarer" : "erik", "jacques" : "dwayne"])
+ * 
+ * keys(names)  will  not  contain "truilkan" after map_delete(names,"tru‐
+ * ilkan") is called [unless ("truilkan", *) is subsequently added back to
+ * the mapping].
+ *
+ */
+void map_delete( mapping m, mixed element );
+
+/**
+ * keys()  -  return an array of the keys from the (key, value) pairs in a
+mapping
+ *
+ * keys() returns an array of keys (indices) corresponding to the keys  in
+ * the (key, value) pairs stored in the mapping m.
+ * 
+ * For example, if:
+ * 
+ * mapping m;
+ * m = (["hp" : 35, "sp" : 42, "mass" : 100]);
+ * 
+ * then
+ * 
+ * keys(m) == ({"hp", "sp", "mass"})
+ * 
+ * Note:  the  keys  will not be returned in any apparent order.  However,
+ * they will be returned in the same order  as  the  corresponding  values
+ * (returned by the values() efun).
+ *
+ */
+mixed *keys( mapping m );
+
+/**
+ * filter_mapping()  -  remove some elements of a mapping based on a
+function
+ *
+ * Returns an mapping with the same keys as  map  whose  items  have  been
+ * mapped  throught  'ob->fun()'  or 'f'.  The function is called for each
+ * element in 'arr' and the return value is  put  back  in  that  spot  in
+ * 'arr'.   'extra' and following are passed as parameters to the function
+ * after the item.
+ *
+ */
+mapping filter_mapping( mapping map,
+                        string fun,
+                        object ob,
+                        mixed extra... );
+mapping filter_mapping( mapping map, function f, mixed extra... );
+
+/**
+ * allocate_mapping() - pre-allocate space for a mapping
+ *
+ * Returns a mapping with space for 'size' elements preallocated.
+ * 
+ * For example:
+ * 
+ * mapping x;
+ * int y = 200;
+ * 
+ * x = allocate_mapping(y);
+ * 
+ * where  y is the initial size of the mapping.  Using allocate_mapping is
+ * the preferred way to initalize the mapping if you have some idea of how
+ * many  elements  the map will contain (200 in this case).  The reason is
+ * that allocating storage all at once is slightly more memory  efficient.
+ * Thus  if  you  are using mappings to store a soul with 200 entries, the
+ * above initialization would be quite appropriate.  Note, that the  above
+ * initialization  does not restrict you to 200 entries.  It just that the
+ * first 200 entries will be stored more efficiently.  Note: if  you  will
+ * be  deleting many elements from the mapping, you should use x = ([]) to
+ * initialize the mapping rather than using allocate_mapping().
+ * 
+ * Note: at this point in time, 'size' is meaningless, x  =  allocate_map‐
+ * ping(200); is equivalent to x = ([ ]);
+ * 
+ * allocate_mapping(mixed *keys, mixed v):
+ * - if value is an array, the returned array has keys 'keys' and values
+ * 'value' (like 3.2.x's mkmapping)
+ * - if it is a function, then the mapping has keys 'keys' and values
+ * evaluate(value, key)
+ * - otherwise, each key has the value 'value'
+ *
+ * allocate_mapping(0) ;
+ * // ([ ])
+ * 
+ * allocate_mapping(25) ;
+ * // ([ ])
+ * 
+ * allocate_mapping( ({ 1, 2, 3 }), ({ "one", "two", "three" }) )
+ * // ([ 1 : "one", 2 : "two", 3 : "three" ])
+ * 
+ * allocate_mapping( users(), (: $1->query_name() :))
+ * // ([
+ * //     OBJ(karahd /std/user#9) : "Karahd",
+ * //     OBJ(gesslar /std/user#2) : "Gesslar"
+ * // ])
+ * 
+ * allocate_mapping( ({ "apple", "banana", "pear" }), 25)
+ * // ([ "pear" : 25, "apple" : 25, "banana" : 25 ])
+ *
+ */
+mapping allocate_mapping( int size );
+mapping allocate_mapping(mixed *key, mixed value);
+