1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
TinyMUX 2.12: LOCAL
Last Update: July 2012
~~~~~~~~~~~~~~~~~~~~~~
Notes on TinyMUX's local.cpp extensions
---------------------------------------
The local.cpp file contains several functions to enable the extension of the
server source code (AKA hardcode). These functions provide an interface to
reduce the need to implement changes within the server code itself.
Developers should be familiar with the TinyMUX source prior to utilizing the
local API. Utilizing the local extensions is just like modifying the server
source code and can cause instability if done improperly.
=============================================================================
API Description
Function: local_startup()
local_startup is called after all normal initialization is complete just
before the game begins to process input and output for connected players.
This function can be used to load databases, perform initialization or other
tasks that need to occur prior to the game being active. The function
accepts no arguments and returns no value.
Function: local_dump_database(int dump_type)
local_dump_database() is called prior to the game performing a database
dump. It is invoked via the periodic dump timer, @restart, @shutdown,
and @dump.
dump_type is one of the five dump type definitions declared in externs.h.
It can be used to perform different procedures depending on what type
of dump the game is performing.
Currently, the following types are available:
DUMP_I_NORMAL -- perform a normal dump
DUMP_I_PANIC -- write a panic database (game output to crashdb)
DUMP_I_RESTART -- game writes database to the inputdb
DUMP_I_FLAT -- game is unloading the db to a flatfile
DUMP_I_SIGNAL -- game is unloading the db to a flatfile via a signal
Function: local_shutdown()
local_shutdown is called after the game database has been saved but the
logfiles remain open. It can be utilized to perform any cleanup prior
to the process being terminated. Database saves need not occur within
local_shutdown since local_dump_database is called prior to it.
Function: local_dbck()
local_dbck is invoked during all database consistency checks (periodic
or manual @dbck).
Function: local_connect(dbref player, int isnew, int num)
local_connect is called when a player connects to the game. The
argument isnew is set to 1 if the player object was just created,
or 0 if it was pre-existing. The number of current connections
is passed via the num argument where any value >1 indicates multiple
connections.
Function: local_disconnect(dbref player, int num)
local_disconnect is called when a player disconnects from the game.
Arguments contain the dbref and the number of connections at the time
of the disconnect. A value of >1 for num indicates the player still
has an active connection.
Function: local_data_create(dbref object)
local_data_create is called when any object is created. Note: this
function catches player creation via @pcreate as well as creations
at the connection screen so is a better location for player based
initialization if required.
Function: local_data_clone(dbref clone, dbref source)
Cloning is a unique creation process so it has a stand-alone handler.
Called after the source object has been cloned and set with all
relevant information.
Function: local_data_free(dbref object)
local_data_free is called after the target object has been cleared of
all information but just prior to it being truly destroyed. This occurs
at the point of true destruction prior to being available to the freelist
not when it is just set GOING.
=============================================================================
Periodic Processing
The TinyMUX local implementation does not provide a function implementing the
functionality of PennMUSH's local_timer() 1 second cycle callback. Instead,
developers should make use of the TinyMUX scheduler to instantiate periodic or
one-shot timers. The scheduler accepts a function pointer to execute at the
designated timeframe. Regularly occuring timers must re-schedule themselves
during the callback execution.
The function format required by the sceduler is:
void funname(void *, int)
The function accepts a void pointer to user data and an integer value.
Most timer functions do not make use of these parameters.
To instantiate a timer, first declare the function to be called. This
example shows a timer that happens only once.
void myTimer(void* pUnused, int iUnused)
{
// ... insert timer code here
}
Once the function is available, it must be scheduled. The following
example is shown using local_statup.
const CLinearTimeDelta period_15s = 15*FACTOR_100NS_PER_SECOND;
void local_startup(void)
{
CLinearTimeAbsolute ltaNow; // declare a time object
ltaNow.GetUTC(); // set the value to UTC
// Schedule myTimer to occur at 15 seconds in the future.
// The final two args to DeferTask are the user data values.
//
scheduler.DeferTask(ltaNow+period_15s, PRIORITY_SYSTEM,
myTimer, 0, 0);
}
If the timer should occur on a periodic basis, it must reschedule itself.
void myPeriodicTimer(void *pUnused, int iUnused)
{
// ... perform processing
//
// Reschedule this timer.
//
CLinearTimeAbsolute ltaNow; // declare a time object
ltaNow.GetUTC(); // set the value to UTC
scheduler.DeferTask(ltaNow+period_15s, PRIORITY_SYSTEM,
myTimer, 0, 0);
}
Individuals using scheduled tasks should examine the CScheduler and
CLinearTimeAbsolute classes for more details on their use.
|
