2009.07.29 14:24

Project Darkstar Server Application Tutorials (1)

Coding Project Darkstar Server Applications

This chapter presents the fundamental concepts of how to code game server applications in the Project Darkstar
Server (PDS) environment. Understanding these concepts is the first step on the path to building massively
scalable, reliable, fault-tolerant, and persistent network games.

Goals and Philosophy

In order to understand the Project Darkstar Server (PDS) coding model, it is useful to understand the system's
goals. The fundamental goals are as follows:

Make server-side game code reliable, scalable, persistent, and fault-tolerant in a manner that is
transparent to the game developer.

Present a simple single-threaded event-driven programming model to the developer. The developer
should never have his or her code fail due to interactions between code handling different events.
Applications coded to run in the PDS environment are called PDS applications.

Approach to Execution

Tasks and Managers

From the point of view of the PDS application programmer, PDS applications execute in an apparently
monothreaded, event-driven model. The code handling the event appears to the coder to have sole ownership of
any data it modifies. Thus, execution is both race-proof and deadlock-proof. Under most conditions there is no
need to synchronize application code and, in fact, attempting to use the synchronized keyword in Managed
Objects1 can cause subtle bugs.

In actuality, the system has many threads of control all simultaneously processing their own events. These
threads of control are called tasks. The system keeps track of what data each task accesses. Should a conflict
arise, one task is aborted and scheduled for retry at a later date so that the other task can complete and get out of
the way.

Tasks are created by PDS managers. a PDS application uses these managers to effect actions in the PDS
environment and the outside world.

There are three standard managers in the system. In addition, arbitrary managers may be coded and added to the
PDS environment. The standard managers are:

Task Manager
A PDS application can use the Task Manager to queue tasks of its own. Tasks can be queued for
immediate execution, delayed execution, or periodic execution. Tasks created from within other tasks
are called child tasks. The task that queued the child task is called the parent task. Multiple child tasks
queued by the same parent task are called sibling tasks.

Data Manager
A PDS application can use the Data Manager to create and access persistent, distributed Java objects
called Managed Objects. The PDS application is itself composed of Managed Objects.

Channel Manager
A PDS application can use the Channel Manager to create and control publish/subscribe data channels.
These data channels are used to communicate between groups of clients and the server.

A PDS application gets access to core PDS functionality through the AppContext class, which provides
methods to obtain references to the various managers.

Task Ordering

Tasks that handle events created by a client are guaranteed to execute in order. A task to handle a client event
that occurred later in time will not start executing until the tasks to handle all earlier events generated by the
same client have finished. A child task is ordered with regard to its parent task, but not with regard to its
siblings. This means that execution of a child task will not begin until execution of the parent has completed.
There are, however, no guarantees among sibling tasks as to order of execution.

Important: There are no other order guarantees in the system. In particular, execution of tasks to handle
events of different users are not guaranteed to start executing relative to each other in the order they
arrived at the server.2

Task Lifetime

Tasks must be short-lived so that they do not block access for an inordinate amount of time to resources that
might be needed by other tasks. The PDS is configured by its operator with a maximum task execution time (the
default is 100 milliseconds). Any task that does not finish within that time will be forcibly terminated by the

If you have a task that runs too long, there are two approaches to reducing its execution time:

Split it up into a chain of child tasks, each of which handles one discrete portion of the problem, and
then queues the next task in sequence. This is known as continuation-passing style.

Move the time-consuming calculations into a custom manager that queues a result-task when the
calculations are complete.

Each approach has its advantages and disadvantages. The first is easier for simple problems that lend themselves
to serial decomposition. Care must be taken that each task ends with the data in a sensible and usable state,
because there is no guarantee as to exactly when the next step will be executed.

A special case of this approach is where parts of the problem are separable and handleable in parallel. In this
case, the time to complete may be reduced by launching parallel chains of tasks. These parallel chains, however,
have no guaranteed ordering in relation to each other, so the work they perform must really be independent of
each other.

The second approach is easier for problems that don't decompose well into small, discrete components; however,
it requires the writing and installation of a custom PDS manager. (Writing custom PDS managers will be
covered by a separate document explaining how to extend the PDS environment.)

A particularly important case is code that has to go into system calls that can block for more then the task
execution lifetime. These must be implemented through a custom manager in order to produce a robust PDS

1 ) PDS applications are made out of Managed Objects, which are fully explained in “Managed Objects and Managed
References,” below.

2) This also implies that tasks generated by two different clients will not necessarily get processed in the relative order they w
ere created on the clients. In practice, this is generally not true in online games anyway unless special pains are taken to make it so, since simple variations in latencies in the two clients' net communications to the server can reorder their arrival.

Trackback 1 Comment 3
2009.07.28 17:26

Project DarkStar Server Application Tutorial List

Project Darkstar Server

Application Tutorial




Introduction vi

Coding Project Darkstar Server Applications 1


Goals and Philosophy 1


Approach to Execution 1

Tasks and Managers 1

Task Ordering 2

Task Lifetime 2


Managed Objects and Managed References 3

Accessing Managed Objects through Managed References 3

Designing Your Managed Objects 4

The Player Managed Object 5

The AppListener 6


Locating the Server API Classes 9

System Classes and Interfaces 9

Task Manager Classes and Interfaces 10

Data Manager Classes and Interfaces 10

Channel Manager Classes and Interfaces 11


Lesson One: Hello World! 12


Coding HelloWorld 12

HelloWorld 12


Running HelloWorld 13

Rerunning HelloWorld 14


Lesson Two: Hello Logger! 17

Coding HelloLogger 17

HelloLogger 17

The Logging Properties File 18

Lesson 3: Tasks, Managers, and Hello Timer! 19


Tasks 19


Managers 19


Coding HelloTimer 20

HelloTimer 20

Project Darkstar Server Application Tutorial 05/29/09 iv


Lesson 4: Hello Persistence! 23


Coding HelloPersistence 23

HelloPersistence 23


Coding HelloPersistence2 25

HelloPersistence2 26

TrivialTimedTask 27


Coding HelloPersistence3 28

HelloPersistence3 29


Lesson 5: Hello User! 32


Knowing When a User Logs In 32

HelloUser 32


Direct Communication 33

HelloUser2 33

HelloUserSessionListener 34

HelloEchoSessionListener 36


Running the Examples 38


Lesson 6: Hello Channels! 39


Coding HelloChannels 39

HelloChannels 39

HelloChannelsSessionListener 41

HelloChannelsChannelListener 43


Running HelloChannels 44


Conclusion 45


Best Practices 45


Things Not Covered in This Tutorial 47


Appendix A: SwordWorld Example Code 49

Sword World 49

SwordWorldObject 52

SwordWorldRoom 54

SwordWorldPlayer 58

Trackback 0 Comment 3

티스토리 툴바