1. What is ProSim4

There are 2 kinds of discrete event simulation systems:

• Event based
• Process based

In process based simulation systems, you write one function for each type of entity in the simulation. The entities schedule their actions themselves using simulation functions. Since there are usually a small number of different types of entities in a simulation, the result of using process based simulation is writing a small number of functions. Another advantage of process based simulation is simplicity. The simulated entity is programmed using very "natural" actions.

2. Intro to ProSim4

   void Server(void *param)
   {
      void *Client;

      while (1)
       { /* --------------------------------------------
	    Check if there are any clients in the queue
	    -------------------------------------------- */
	 if (MyQLength() == 0)
          { Passivate(COMPLETELY, NULL); /* Queue empty, passivate... */
          }

	 /* ----------------------------------------
	    Arriving client will wake up Server()
	    ---------------------------------------- */
         Dequeue(HEAD, &Client,NULL,NULL,NULL); /* Remove first client */
         Hold(drand48() + 0.2);		        /* Service delay       */
         ReActivate(Client, DONE, 0);           /* Reactive client     */
				   /* Note: client will receive
				      the "DONE" value when it returns
				      from Hold() */
        }
   }

	PCBType *myServer;
	....
	myServer = Generate("myServerName", Server, param);

	MYSELF->Name

	MYSELF->ArrivalTime

• int State: store that current state. The legal values are defined in the prosim4.h header file. See below for the meaning for certain values: click here.

• double ArrivalTime: The time that this entity was created. The function "GetMyArrivalTime()" will return this value.

• double EventTime: next event time. This is the time that this entity will do something.

• int pos: The position of this ProSim4's entity in the ProSim4 scheduler heap. (ProSim4 uses a heap - sorted on EventTime - to find the entity with the smallest EventTime. Control is passed to this ProSim4 entity.)

• struct QElem *Queue: its queue. The queue contains a list of ProSim4 entities. The idea is that the ProSim4 entities in the queue wants this ProSim4 entity to do something for them.

• long NQueue: the length of the queue.

• struct TOElem TOHeap: heap to organize timeout requests.

   typedef struct ProSim4Message
   {  double Time;                 /* Time stamp... (NetSim4 needs it) */
      struct ProSim4Message *next; /* For chaining ProSim4 messages    */
      void *message;               /* The actual message...
                                      You can link anything here !!!   */
   }  MessageType;

	#include "ProSim4.h"	/* ProSim4 header file.... */

	/* ------------------------------------------------------------
	   Write C functions to define behavior of simulation entities
	   ------------------------------------------------------------ */
	void Client(void *param)
	{  /* Simulate a client */
	   ....
	   Terminate();
	}

	void Server(void *param)
	{  /* Simulate a server */
	   ....
	   Terminate();
	}

	void Generator(void *param)
	{  /* Generates clients at random time intervals (arrival stream) */
	   while(1)
	    { Hold(some random time);
	      Generate("Client", Client, param);
	    }
	}

	/* ------------------------------------------------------
	   main() creates the simulation entities and waits...
	   ------------------------------------------------------ */
	main(int argc, char **argv)
	{
	   Gen = Generate("ArrivalGenerator", Generator, param1);
	   Serv = Generate("Server", Server, param1);

	   Initialize variables for tallying performance statistics...
	   StartSimulate(warmup-time);  /* To get system in a steady state */

	   Re-Initialize variables for tallying performance statistics...
	   StartSimulate(sim-time);     /* To get performance statistics */

	   Print performance statistics...
	}

• void InitProsim(MaxNProcess, MaxNQElems, MaxNTimeHeap):
  1. MaxNProcess is # of entities in simulation
  2. MaxNQElems is # of queueing requests (one thread can make multiple queueing requests...)
  3. MaxNTimeHeap is # of entities in scheduler's heap. This value must be at least equal to MaxNProcess...

  Always call the function InitProsim() before you do any in ProSim4 !!!

• void StartSimulate(double Time):

  After creating all the simulation entities (by using Generate(), click here). the simulation is started by invoking StartSimulate(SimTime). This function must be invoked from within the main() function of the C program.

6.2. Thread Creating/Destruction Primitives

• void Hold(double T):

  Make thread wait T time units before it runs again. The thread will execute again when simulation time is equal to "Now + T".

  NOTE: The thread that executed a Hold() call will NOT run until simulation time is "Now+T".

  This function is often used to simulate serving a client, see the example above: click here.

• void HoldUntil(double T):

  This function is similar to Hold(). Make thread wait until the simulation time Now is equal to T before the thread runs again. The thread will execute again when simulation time is equal to "T".

• int Passivate(double T, long *Param):

  This function - like Hold() - will also make the thread wait T time units before it runs again. The difference between Passivate() and Hold() is that the thread will run immediately when it is re-activated (by some other thread using the primitive ReActivate()).

  NOTE: If T == COMPLETELY, then the thread will not run again until it is re-activated by some other thread.

  NOTE: you must provide a "reason" for re-activation in the ReActivate() call that is different than the default return value TIMEOUT. The "reason" value is passed as a parameter of ReActivate() and it is also the return value of Passivate !!!

  NOTE: Passivate is also used if you want to use ProSim4's timeout service. First, you set the timeout requests using:

    SetTimeOut(Time1,Signature1,&pos); <- sets timeout with cancellation
    SetTimeOut(Time2,Signature2,NULL); <- sets timeout with no cancellation
  

  Now you can call:

  	r = Passivate(COMPLETELY, &out);
  

  If r == TIMEOUTSERVICE, then one of the timeout values has been reached. The out (a long variable) will be equal to one of the values Signature1 or Signature2. You can use this value to decide what to do next.

  This function is often used by a "server" type entity to wait for the arrivals of clients; see the example above: click here.

• int PassivateUntil(double T, long *Param):

  Works just like Passivate(), except using time parameter "T-Now". All notes of Passivate() also apply to PassivateUntil().

• void ReActivate(PCBType *PCBPtr, int Result, long Data):

  If the thread PCBPtr made a call to Passivate(T,Param) to stop, the ReActivate() call will make the thread run immediately. In addition:

  1. Passivate(T,Param) will return the value Result
  2. The Param (a long * variable) in Passivate(T,Param) will be updated to the value Data. (This feature is used by the timeout server - see timeout.c)

  However: The ReActivate() call has absoultely no effect if the ProSim4 entity PCBPtr was stopped (paused) using the Hold() call.... (So you can use ReActivate() on a server entity that made a Hold() to simulate non-pre-empty service !!!)

6.4. Queueing Functions

• void Enqueue(int pos, void *Server, void *In, void *Local, void *Out) :

  Puts the simulation entity that calls the Enqueue() in the queue of the simulation entity Server. The variable pos controls the way you enter the queue (the variable Queue in the PCB) and the value of pos can be one of HEAD or TAIL,

  You can pass 3 pointers to your own variables to the Server. What I have in mind is to distinguish "input", "local" and "output" variables. Input variables are read-only and output variables are un-initialized write only variables. The local variables are read/write. But there is nothing in ProSim4 to force you to abide to this policy... If you do not want to pass any pointer, you must pass NULL.

• void Dequeue(int pos, void **Client, void **Inp, void **Local, void **Out):

  Remove a simulation entity from my queue. The variable pos controls the way the entities are dequeued from the queue (the variable Queue in the PCB). If pos == HEAD, you remove from the start, and if pos == TAIL, you remove from the tail. The FIFO queue is implemented by using pos == TAIL in Enqueue() and pos == HEAD in Dequeue().

  Notice that you will pass 3 void** (address of pointer variables) variables. You will obtain the 3 pointer values that was passed in Enqueue(). If you do not want to obtain a pointer for some variable, pass NULL in the corresponding field.

• void QLength(PCBType *Server):

  Returns the length of the queue of simulation entity Server.

• void MyQLength():

  Returns the length of my own queue.

6.5. Randomization Functions

• void InitRandom(unsigned int seed):

  Re-seed all NUM_STREAMS streams using the value seed.

• double Uniform(int stream):

  returns a uniformly distributed random double number in interval (0..1) taken from the stream stream.

• double D_Uniform(double a, double b, int stream):

  returns a uniformly distributed random double number in interval (a..b) taken from the stream stream.

• long I_Uniform(int a, int b, int stream):

  returns a uniformly distributed random long number in interval (a..b) taken from the stream stream.

• double Exponential(double mean, int stream):

  returns a exponentially distributed random double number with mean of the distribution equal to mean taken from the stream stream.

• double RateExponential(double rate, int stream):

  returns a exponentially distributed random double number with rate equal to rate taken from the stream stream.

  NOTE: This function is often used in "Generator"-type simulation entities to generate clients that arrive with an exponential arrival rate (memory-less proporty).

  NOTE: Servers with expenential rate service time will also use this function in the simulation.

• void InitTimeOutServer(int MAX):

  This function will start the ProSim4 timeout server thread. The parameter MAX is the maximum number of ProSim4 entities that can request time out. (To speed up time out processing, the requests are organized into a two-leveled heap. The MAX value is used to allocate memory space for the array containing the heap).

  NOTE: if you need to use timeout, you must call InitTimeOutServer(MAX) right after you called InitProsim().

• void InitTimeOut(int MAX_TOs):

  Each ProSim4 entities that want to request time out must call InitTimeOut(MAX_TOs) first. The values MAX_TOs is the maximum number of time out requests that this simulation entity will make. InitTimeOut(MAX_TOs) will allocate space for MAX_TOs timeout request records in the TOHeap of the PCB.

• void SetTimeOut(double Time, unsigned long Sign, unsigned short *pos):

  Make a timeout request with expiration time Time. The parameter Sign is a unique "signature" that you may pass to ProSim4 to identify a specific timeout request. This Sign value will be returned by Passivate() upon timeout expiration. (For details of Passivate(): click here.)

  The parameter pos is the position of the time out request in the entity's local timeout heap. It is passed in to speed up timeout cancellation (you will need the position to delete quickly from the heap). If you will not need to use the time out cancellation feature, you can set pos==NULL.

• void CancelTimeOut(unsigned short pos): Cancels the timeout request identified by pos. (You will need to have passed the pos variable to SetTimeOut() when you made the time out request...)

1. In main():

      InitProsim(.., .., ..);
      InitTimeOutServer(MAX entities requesting timeout);
   

2. In each simulation entity that requests timeout:

      InitTimeOut(MAX # timeout request to be made by this entity);
      ....
      unsigned short pos;
      SetTimeOut(Time1, Signature1, &pos);  /* Make cancellable request */
      ....
      unsigned short pos;
      SetTimeOut(Time2, Signature2, NULL);  /* Make uncancellable request */
      ....
      CancelTimeOut(pos);			 /* Cancel request */
   

   6.8. Abnormal Abort

   When ProSim4 detects that has reached certain system limits, it will print an error message and call the "OnAbort()" function. ProSim4 provides a dummy OnAbort() function for the user. But if you like to print out values of some internal variables when the system aborts, you can provide your own OnAbort() function.

   7. Debugging Simulation Programs

   Since ProSim4 manipulates the system stack, the use of a debugger if of limited effectiveness. You still can use dbx or gdb, but you will only be able to see the variables of the current active thread - variables of other threads (which are waiting to be executed) cannot be examined. The best way is to structure your program modularly and use a lot of "printf()" calls.

   8. Examples Simulation Programs

   • main1.c

     Implements a D/U/1 queueing system. There is one server entity and one generator entity in the simulation. The generator entity will client arrivals with constant rate (1 client per time unit). Each client will enqueue itself to the server (to get service). The service time is random, uniform [0.2 - 1.2].

   • main2.c

     Implements a M/M/2 queueing system. There are 2 server entities and one generator entity in the simulation. The generator entity will client arrivals with exponential rate. Each client will enqueue itself to the both server (to get service) and will only leave when it has receive service from both servers. The service time is exponentially distributed.

   • main3.c

     is a test program that I made when I added the capability to pass a parameter to the ProSim4 thread in Generate(). This program also tests/illustrates the new return capability of ReActivate()

   • main4.c

     is a test program for SendMessage_FIFO() and RecvMessage_FIFO().

   • main5.c

     is a test program for ProSim4's time out facility.

     The test programs can be run after you have gotten and installed the ProSim4 library and header file. See below. The accompany Makefile can be obtained here: click here.

   9. Getting ProSim4

   You need to get the following 2 files to install ProSim4:
   • The ProSim4 header file: click here
   • The ProSim4 library: click here (Use "Save Link As" in your browser to get this library)

   X. Implementation of ProSim4

   ProSim4 is built on top of the functions NewProcess() and Transfer() in the sys4.c file which provides an efficient threading system:
   • NewProcess() prepares a C function to become a thread and
   • Transfer(t1,t2) passes control from thread t1 to t2.

   The main simulation engine is the "scheduler" and the scheduler is also a thread. User can call the scheduler from the main C program using the StartSimulate primitive defined in prosim4.c. As a user, you don't have to understand the internals of the package, but it will help you write your simulation programs if you do. So let me briefly describe NewProcess and Transfer below.

   Each thread in ProSim4 is given a workspace, which is a large array of bytes. The workspace is used for holding the stack (procedure calls & return addresses and local variables of procedures) of the thread. So the workspace is private.

   The state of the thread consists of all volatile information, i.e., registers, stack pointer, program pointer, workspace address etc. These info. are stored on the stack (in the workspace). To get to these information, you need a stack pointer. This pointer is stored in the PCB (process control block) of the thread. (See struct PCB in prosim4.h.)

   The ProSim4 PCB contains a lot of important information about the simulated entity: arrival time, status (active or waiting), next event time, etc. A thread can be fully determined by giving the address of its PCB, since then the scheduler can determine its workspace and the stack pointer. Using the stack pointer, the scheduler can locate all the register values and program counter of the thread.

   To restart the thread where it was halted, the scheduler pops back the saved register values back from the stack. But be careful that there are 2 stacks (2 threads !) involve: one stack from the thread that is going to relinquish control and the second stack is from the thread that will get control. The Transfer(t1,t2) function therefore taks 2 inputs: the 2 PCB's.

   The Transfer function perform the following:

   1. Note: The PC of the thread t1 is already save on the stack because of a procedure call to Transfer() You don't have to save that again.
   2. Save all registers of the first process on his stack. Then save the stack pointer in the process's PCB.
   3. Switch stack. This is accomplished by putting the stack pointer value obtained from the second PCB into the SP register.
   4. Pass control to the second process. This is accomplished by popping all registers back and do a return, which will pop the Program counter, so doing a jump into the code of the second process (recall that the PC was pushed by the process implicitly when it calls Transfer. So this return will make the second process to resume from where it has left off when it did a Transfer call.
   All is well if you have the stack set up. Now, what if the process is not started yet. How do you start it ? The answer is: you fake an initial stack that is exactly the same as when the process did a transfer call. This is the job of NewProcess(). You will see that NewProcess pokes some addresses in the bottom of workspace. It is setting up an initial stack that looks exactly the same as when the process has been halted due to a call to Transfer. For instance, the return address poked is the start address of the procedure. So when a return instruction is executed, it will jump right to the start of the procedure. This is how to make a function into a thread.