|
|
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:
24
25 void initialize()
26
27 Called when the system starts up after a reboot.
28
29 void restored()
30
31 Called after the system has restarted from a state dump.
32
33 string path_read(string path)
34
35 Used to translate a path for an editor read command. If nil is
36 returned, the file cannot be read.
37
38 string path_write(string path)
39
40 Used to translate a path for an editor write command. If nil is
41 returned, the file cannot be written to.
42
43 object call_object(string objname)
44
45 Get the object named by objname as the first argument of a call_other().
46 compile_object() may be called from here.
47
48 object inherit_program(string file, string program, int priv)
49
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.
53
54 string path_include(string file, string path)
55
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.
59
60 void recompile(object obj)
61
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.
68
69 object telnet_connect()
70
71 Return an object for a new connection on the telnet port.
72
73 object binary_connect()
74
75 Return an object for a new connection on the binary port.
76
77 void interrupt()
78
79 Called if the driver receives a kill signal. The function should
80 shut down the system, and possibly dump state.
81
82 void compile_error(string file, int line, string err)
83
84 Handle a compile-time error; there can be several for the same
85 LPC file before a runtime error results (calling runtime_error).
86
87 void runtime_error(string error, int caught, int ticks)
88
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.
95
96 void atomic_error(string error, int atom, int ticks)
97
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.
104
105 int compile_rlimits(string objname)
106
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).
118
119 int runtime_rlimits(object obj, int stack, int ticks)
120
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.
126
127 void remove_program(string objname, int timestamp, int index)
128
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.
137
138 - in every object:
139
140 void create()
141
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.
145
146 - in the user object (returned by driver->telnet_connect() or
147 driver->binary_connect()):
148
149 int open()
150
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.
159
160 void close(int flag)
161
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.
166
167 void receive_message(string message)
168
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.
174
175 void message_done()
176
177 This function is called when a string sent by send_message was
178 fully transmitted.
179
180 On startup, the system is configured with a configuration file, which
181 must specify the following configuration parameters:
182
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.
235
236 Examples of the auto object, driver object and config file are present
237 in the kernel library, which is distributed with DGD.
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.