DESCRIPTION OF SIMULATOR TIME FACILTIES
Luis Ortiz
Michael Kearns

Below are some (rough) man-page-like descriptions of the new facilities.

NAME:
            simTime - get simulator time in secs

SYNOPSIS:
            #include "simTime.h"
            #include "MarketView.h"
            simTime_t simTime(const MarketState *mState, simTime_t *t);

DESCRIPTION:
            simTime() returns the time in secs since "midnight," where "midnight" is defined relative to the simulator execution. If t is non-NULL, the return value is also stored in the memory pointed to by t. (Similar to the standard time() function.)

RETURN VALUE:
            On success, the value of simulator time in seconds since "midnight" is returned.

NOTES:
            simTime() needs mState as an argument because the simulator time is part of the market state. This time is obtained from the time-stamp given inside the last Island html (book) file processed (be it in a historical or live simulation). Note that currently, at every round, the simulator first gets a new Island html file before continuing, be it from the historical repository during historical simulations or the last (special) book placed in the stock's repository for live simulation---which we later copy to another file with a time-stamp as a suffix to its name. So from the standpoint of the clients, the simulator will seem to have stopped!

            For "asynchronous" simulation (be it a real or historical), this is because any information send to the clients won't change until the server gets a new Island file. Among possibly other things, this implies that any new orders received after the last Island file was processed will not be effectively processed until the simulator gets a new Island file.

            For "synchronous" simulations this means that no further communication with the clients will happen until the simulator gets a new Island file.

NAME:
            simDiffTime - calculate simulator time difference

SYNOPSIS:
           #include "simTime.h"
           double simDiffTime(simTime_t time1, simTime_t time0);

DESCRIPTION:
           The simDiffTime() function returns the number of seconds elapsed between time time1 and time time0. (Similar to the standard     difftime() function.)

The following is an auxiliary function.

NAME:
            simCTime - transform simulator time to ASCII

SYNOPSIS:
            #include "simTime.h"
            char *simCTime(const simTime_t *timep);

DESCRIPTION:
            The simCTime() function converts the simulator time timep into a string of the form "10:49:08\n" The return value points to a statically allocated string which might be overwritten by subsequent calls to the simCTime() function. (Similar to the standard ctime() function.)