Wormhole Manual


Table Of Contents



1 Introduction

1.1 Overview

Wormholes provide a way to connect two or more CSIM simulations together and syncronize the simulations' events. The wormhole connections are implemented through the network, so simulations running on different machines and even different platforms can be connected.

1.2 Definitions & Terms

Wormhole
An event syncronized connection between two simulations.

2 Useage

2.1 Sending Data Through Wormholes

If the data structures being sent through a wormhole contain pointers to other data, these pointers will be invalid on the opposite end of the wormhole because the two simulations are separate programs with separate memory spaces. The solution is to "pack" the data into a new structure that contains all of the data. Four function 'templates' have been supplied to perform parts of this operation. They are located near the top of wormholelib.sim box. Overwrite them as necessary.

2.2 Building A Simulation Using Wormholes

When building this simulation be sure to build and link in wh_socket.o, wh_queue.o, and wh_connect.o.

2.3 Connecting Simple Wormholes

A simple wormhole allows one connection between two and only two simulations. Due to the method in which a network connection is formed, one end of the wormhole must be selected to be a client and the other a server. The only real difference between the two will be how they connect and has no bearing on how the simulation runs. A server is denoted by placing the string, "server(port_num)" into its instance name, where port_num is the machine's port number on which the socket will be connected. A client is denoted by placing the string, "client(port_num)" into its instance name, where port_num is the machine's port number on which the socket will be connected. Note: If port_num is left blank in either the server or the client, a default port number will be used. Also, when exitting simulations connected by a wormhole, be sure to exit the client first.

2.4 Connecting Multi-Wormholes

A multi-wormhole allows one connection between any two simultations. Connection information is read from a file named connect.dat which the simulation writer must write. This file contains a database of connection methods for each wormhole in that simulation. The instance names of connecting wormholes must match each other. The format of a client record is as follows:

<wormhole_name>	<host_name>	<port_num>

Where <wormhole_name> is the instance name of the wormhole, <host_name> is the name of the host (computer) running the simulation with the server wormhole, and <port_num> is the port on that host where the server is accepting connections. The format of a server record is as follows:

<wormhole_name>

In addition to record entries comments and directives are allowed in the connection file. Comments begin with a '#' and end at the end of the line. Presently there is only one directive. The port directive defines the port on which the server wormholes will accept incoming wormhole connections. The port directive is used as follows:

%port	<port_num>

3 Technical

3.1 The Wormhole Mechanism

Wormholes work by creating an upper tier scheduler for the simulations. A simulation will be scheduled to run if the time to its next big event is the shortest of all of the simulations. Time of the next big event being the next time slot where events are scheduled, because multiple events can be scheduled for the same. When the time of the next event of two simulations is the same both will run concurrently. If, while any simulation is running, data is received on a wormhole's simulation port that simulation will halt for the receiving simulation to reschedule and renegotiate which simulation will run.

.

4 Wormhole Example

.

Aron Rubin