|First code: This is the first code release of Space Tyrant. This is an early stage of development and, at this point, only implements the listening thread, the two IO threads for each player connection, and a skeletal game logic thread that does little beyond proof-of-concept code.|
The design of the code was discussed in this article so you should probably go back and read that article if this is your first brush with this project.
The first code release -- what we will be discussing in this article -- is online as spacetyrant1.c. Download it as well as the shell script you’ll need to compile it: makeit1.sh. The script should work under both Linux and Mac OS X. The code will require a single line change to compile under Mac OS X. Search the code for the string OSX to find the line to decomment and the corresponding line to comment out.
Currently, the program allows multiple people to connect using telnet and echos anything they type to all other connected sessions. Some familiarity with the C programming language will be assumed in this article and those to follow.
Configuration constants: There are several ‘configuration constants’ defined by #define statements. The key constants and their meanings are:
MAXTH: This number represents the maximum number of users that can connect simultaneously. This constant is used to set limits on loops and to define the number of elements in various arrays. This number must be a power of 2.
MAXTHBITS: This is simply the number of bits necessary to form an unsigned int to index into arrays of MAXTH size. This number is used to declare bit fields for use with various items that occur MAXTH times. In the code we use a MAXTH of 256 and since 2^8 equals 256, MAXTHBITS is set to 8. Note that if you change MAXTH, you must make an appropriate change to MAXTHBITS!
MAXBUF: This is the number of buffers used in various places. For example, the input threads each get MAXBUF numbers of buffers.
MAXBUFBITS: This number matches MAXBUF in that it is the number of bits necessary to express the number MAXBUF in the same way that MAXTHBITS relates to MAXTH.
MAXLINE: This is the maximum length (in bytes) that is allowed for network input and output. The IO buffers, for example, are declared to be size MAXLINE + 1. The ‘+ 1’ is to allow room for a terminating 0.
RADPAD: This is added to MAXLINE to determine the length of a radio buffer. Radio buffers need to be larger than IO buffers since they must allow room for headers.
Data structures: Next, we declare a struct to contain most of the data associated with each thread. Note that this struct contains no player-specific data; it is used only to contain the data necessary to define an input thread and an output thread used to define one user connection. ‘threc’, as we will call the struct, will be an array with MAXTH elements. It will contain the thread ID of both the input and output threads, the timestamp of the last input from the input thread, the number of the socket descriptor, and various flags and indexes that will be used to coordinate the activities of the input, output, and game logic threads. Look at the code comments themselves for details on the variables.
Note that MAXBUFBITS is used to declare the size of inndx, outndx, inptr, and outptr. These variables, when incremented past the number of buffers, wrap back to zero, making it easy to implement ring buffers. That is why the MAXBUF number must be a power of 2.
The thread functions: In this program main() has two primary functions. First, it calls any initialization functions and clears the various data structures and spawns any other permanent threads. Second, it goes into an endless loop of accepting user connections and spawning IO threads to handle the newly connected users.
The next thread function, gameloop(), has the hard job. It constantly loops though the input buffers, looks for input that needs to be processed, and does it. While looping around the buffers, it also looks for input threads that have gone idle and terminates (‘reaps’) them. Currently, the only input processing it does to call a function named broadcast() with any data it finds in the input buffers. The broadcast() function simply copies the input to output buffers. This bit of processing is for proof-of-concept purposes only and will be replaced by actual game logic as it is developed.
The last important thread functions, userin() and userout(), exist in multiple pairs to perform network input and output duties for each connected user. The userin() thread reads the network connection and loads data into the next available input buffer (‘inbuf’). It then timestamps it, and goes back to waiting for more input. The userout() thread loops continously waiting for anything to appear in the next output buffer (‘outbuf’). When new data is placed in an output buffer by the gameloop() thread, userout() writes it to the user’s network socket.
Note that because userout() and gameloop() loop continously, they sleep after each ‘idle’ loop. That is, when they pass through their logic loop and find no actual work to do, they call the usleep() function to sleep a tiny fraction of a second. This sleeping prevents them from consuming unnecessary processor cycles.
[Update, June 25, 2005: A Space Tyrant home page has been created as a central index to the various ST articles, links, and files.]