source navigation ]
diff markup ]
identifier search ]
file search ]
Version: [ 1.0.a0 ] [ 1.1 ] [ 1.2 ] [ 1.2p1 ] [ 1.2p2 ] [ 1.2p3 ] [ 1.2p4 ] [ 1.2.151 ]

  1    DGD, which stands for Dworkin's Generic Driver, is a mud server that
  2 uses the same overall design as the LP server made by Lars Pensjö.
  3 However, there are several important differences: DGD uses less memory
  4 because it is disk-based; it can dump state and later restart from a
  5 state dump; it uses LPC as an internal interpreted language, but also
  6 offers the option of precompiling LPC objects to C, making them part of
  7 the program itself.
  8    DGD has two special objects which determine the interface with the 
  9 server for all other objects: the auto object and the driver object.
 10    The auto object (short for automatically inherited object) is
 11 inherited by all other objects, except for the driver object.  It can
 12 redeclare the predefined functions (called kfuns, kernel functions)
 13 that DGD provides, and it can also define standard properties that
 14 every object should have.  DGD is made in such a way that some kfuns
 15 <have> to be redeclared in an environment with several users
 16 programming together; for instance, by default there is no file security.
 17 The auto object has some other special properties; static functions
 18 declared in the auto object cannot be called using this_object()->func()
 19 (i.e. they behave like kfuns).
 20    The driver object defines several functions which are called by the
 21 driver, mostly to translate pathnames.
 22    The following functions will be called by the driver:
 23  - in the driver object:
 25     void initialize()
 27         Called when the system starts up after a reboot.
 29     void restored()
 31         Called after the system has restarted from a state dump.
 33     string path_read(string path)
 35         Used to translate a path for an editor read command.  If nil is
 36         returned, the file cannot be read.
 38     string path_write(string path)
 40         Used to translate a path for an editor write command.  If nil is
 41         returned, the file cannot be written to.
 43     object call_object(string objname)
 45         Get the object named by objname as the first argument of a call_other().
 46         compile_object() may be called from here.
 48     object inherit_program(string file, string program, int priv)
 50         Get the object named by program as an object to inherit.  The third
 51         argument is 1 for private inheritance, 0 otherwise.
 52         compile_object() may be called from here.
 54     string path_include(string file, string path)
 56         Used to translate include path <path> upon compilation of the
 57         object with filename <file>.  If nil is returned, the file <path>
 58         cannot be included.
 60     void recompile(object obj)
 62         If an object A is loaded, A inherits B, B inherits C, and the
 63         version of C inherited by B is out of date, recompile(B) will be
 64         called in the driver object.  If B should actually be recompiled
 65         (inheriting the new version of C from B), the driver object must
 66         destruct B; if this is done, A will inherit the most recent
 67         versions of B and C.
 69     object telnet_connect()
 71         Return an object for a new connection on the telnet port.
 73     object binary_connect()
 75         Return an object for a new connection on the binary port.
 77     void interrupt()
 79         Called if the driver receives a kill signal.  The function should
 80         shut down the system, and possibly dump state.
 82     void compile_error(string file, int line, string err)
 84         Handle a compile-time error; there can be several for the same
 85         LPC file before a runtime error results (calling runtime_error).
 87     void runtime_error(string error, int caught, int ticks)
 89         Called when a runtime error occurs.  <caught> is 0 if the error
 90         is not caught, or 1 + an index in the return value of call_trace(),
 91         indicating the frame in which the error is caught.  runtime_error()
 92         is called with rlimits (-1; -1) so it will not run out of stack or
 93         ticks.  <ticks> specifies the amount of ticks left at the moment
 94         the error occurred.
 96     void atomic_error(string error, int atom, int ticks)
 98         Called when a runtime error occurs in atomic code.  <atom> is an
 99         an index in the return value of call_trace(), indicating the frame in
100         which the atomically executed code starts.  atomic_error() is called
101         with rlimits (-1; -1) so it will not run out of stack or ticks.
102         <ticks> specifies the amount of ticks left at the moment the error
103         occurred.
105     int compile_rlimits(string objname)
107         An object uses the rlimits (stackdepth; ticks) { /* code */ }
108         construct, which can be used to assign arbitrary limits to function
109         call stack depth and ticks; running out of ticks during execution
110         causes an error.  -1 signifies an infinite amount of stack space or
111         ticks.
112         During compilation, driver->compile_rlimits(objname) is called.  If
113         non-zero is returned, the object will be able to use rlimits at
114         runtime with no restrictions.  If 0 is returned,
115         driver->runtime_rlimits() will be called at runtime to further
116         verify if an object is allowed to change its rlimits (resource
117         limits).
119     int runtime_rlimits(object obj, int stack, int ticks)
121         Called at runtime for rlimits constructs not already cleared by
122         compile_rlimits().  If 0 is returned, the rlimits usage is illegal
123         and is aborted with an error.
124         Values for stack and ticks: < 0: infinite, 0: no change,
125         > 0: set to specified amount.
127     void remove_program(string objname, int timestamp, int index)
129         Called whenever the program of a master object is removed (because
130         the object has been destructed, and all clones and inheriting objects
131         have also been destructed).  As this function is called from code
132         that cannot be allowed to abort or fail, it is called with
133         rlimits (-1; -1) and a catch.
134         The "index" is a unique number for each master object, also
135         available with status(obj), which can help distinguishing between
136         different issues of the same object.
138  - in every object:
140     void create()
142         Called in an object which has just been cloned, or if it is not a
143         clone, just before a function is called in it for the first time.
144         The actual name of this function is configurable.
146  - in the user object (returned by driver->telnet_connect() or
147    driver->binary_connect()):
149     int open()
151         A connection has just been opened for this object.
152         For a binary connection, if the return value of this function is
153         non-zero, a UDP channel will be opened for the same object.  UDP
154         datagrams can be received from the same host and port as the TCP
155         connection is on, and after at least one datagram has been
156         received, send_datagram() can be used to send datagrams to that
157         destination.
158         For a telnet connection, the return value will be ignored.
160     void close(int flag)
162         The connection for this object has just been closed.  close() is
163         called when the user goes linkdead, or when the user object is
164         destructed.  The flag argument is 1 if the object is destructed,
165         0 otherwise.
167     void receive_message(string message)
169         This function is called with the text the user typed.  For telnet
170         connections, this is always an entire line, with the newline at
171         the end filtered out.  For binary connections, this is whatever
172         the other side of the connection saw fit to send, without any
173         filtering or processing.
175     void message_done()
177         This function is called when a string sent by send_message was
178         fully transmitted.
180    On startup, the system is configured with a configuration file, which
181 must specify the following configuration parameters:
183 param           type    meaning
184 --------------------------------------------------------------------------
185 telnet_port     number  The port number on which the driver will accept
186                         telnet connections.
187 binary_port     number  The port number on which the driver will accept
188                         binary connections.  Communication on the binary
189                         port is raw TCP/IP without additional protocol.
190 directory       string  The base directory for the system.
191 users           number  The maximum number of active telnet and binary
192                         connections.
193 editors         number  The maximum number of simultaneously active
194                         editor instances.
195 ed_tmpfile      string  The proto editor temporary file (actual files
196                         will have a number appended).
197 swap_file       string  The name of the swap file.
198 swap_size       number  The total number of sectors in the swap file.
199 cache_size      number  The number of sectors in the swap cache in memory.
200 sector_size     number  The size of a swap sector in bytes.
201 swap_fragment   number  The fragment of all objects to swap out at the end of
202                         each thread (e.g. with a swap_fragment of 32, 1/32th
203                         of all objects will be swapped out).
204 static_chunk    number  The size in bytes of a static or dynamic chunk
205 dynamic_chunk   number  of memory.  Memory is divided into static memory
206                         and dynamic memory; static memory is never freed.
207                         Both are allocated in chunks of the specified size.
208                         Setting the size of the static chunk to 0 will
209                         cause the system never to swap out everything to
210                         make more room for static memory, but will also
211                         increase fragmentation.
212 dump_file       string  The name of the state dump file.
213 typechecking    number  If zero, only functions with a declared type are
214                         typechecked.
215                         If one, all LPC functions are typechecked.
216                         If two, additionally, nil (the value of an uninitialized
217                         string, object, array or mapping variable) is a value
218                         distinct from integer 0.
219 include_file    string  The standard include file, which is always
220                         included automatically for each compiled object
221                         (relative to the base directory).
222 include_dirs    string* The standard system include directories (relative
223                         to the base directory).  In the first of those,
224                         the include files which are automatically
225                         generated on startup will be placed.
226 auto_object     string  The file name of the auto object (relative to the
227                         base directory).
228 driver_object   string  The file name of the driver object (relative to
229                         the base directory).
230 create          string  The name of the create function.
231 array_size      int     The maximum array and mapping size.
232 objects         int     The maximum number of objects.
233 call_outs       int     The maximum number of simultaneously active
234                         callouts.
236    Examples of the auto object, driver object and config file are present
237 in the kernel library, which is distributed with DGD.

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~ [ file search ] ~

This page was automatically generated by the LXR engine.
Visit the LXR main site for more information.