DESCRIPTION OF SIMULATOR TIME FACILTIES
Below are some (rough) man-page-like descriptions of the new facilities.
simTime - get simulator time in secs
simTime_t simTime(const MarketState *mState, simTime_t *t);
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.)
On success, the value of simulator time in seconds since "midnight" is returned.
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.
simDiffTime - calculate simulator time difference
double simDiffTime(simTime_t time1, simTime_t time0);
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.
simCTime - transform simulator time to ASCII
char *simCTime(const simTime_t *timep);
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.)