REF TIMES John Gibson Apr 1994 COPYRIGHT University of Sussex 1994. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< DATE TIME AND >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< TIMER PROCEDURES >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< This REF file describes all the procedures in Poplog for dealing with times and dates, CPU times, and timing. CONTENTS - (Use <ENTER> g to access required sections) 1 Date and Time Procedures 2 CPU Time 3 Timer Procedures --------------------------- 1 Date and Time Procedures --------------------------- sys_real_time() -> time [procedure] Returns the time as an integral number of seconds since the standard Unix base date, i.e. 00:00 GMT on 1 Jan 1970 (N.B. this value is a biginteger, not a simple integer). sys_convert_date(time, local) -> string [procedure] Given a time in seconds since 00:00 GMT 1 Jan 1970 (as returned by sys_real_time, or a file date returned by sys_file_stat etc), returns a date string in the standard operating system format, i.e. 'nnn mmm dd hh:mm:ss timezone yyyy' in Unix systems (where nnn is the day name), and 'dd-mmm-yyyy hh:mm:ss' in VMS systems. In VMS systems, the local argument is ignored; in Unix systems it specifies whether time is interpreted as local time (true) or GMT (false), and therefore affects the value of the timezone substring (which depends upon the timezone C library function - see ctime(3) in the Unix Programmers Manual.) sysdaytime() -> string [procedure] Returns the current date and time as a string in the standard operating system form. E.g, in Unix: sysdaytime() => ** Mon Mar 6 12:43:15 GMT 1995 This procedure is the same as sys_convert_date(sys_real_time(), true) ----------- 2 CPU Time ----------- systime() -> hsecs [procedure] Returns the elapsed CPU time for this run of the Poplog system, an integer number of hundredths of a second. The returned value refers to the amount of time spent within Poplog. It does not refer to "real" time and is not effected by any other processes running on your machine timediff() -> float_secs [procedure] Returns the elapsed CPU time since the last call of timediff, as a floating-point number of seconds SECS (the first call produces a meaningless result). This procedure uses systime, so the resolution of the result will be hundredths of a second. The returned value refers to the amount of time spent within Poplog. It does not refer to "real" time and is not effected by any other processes running on your machine ------------------- 3 Timer Procedures ------------------- The variables pop_timeout and pop_timeout_secs are also available for timing-out terminal read operations -- see REF * SYSIO for details. For a general discussion of asynchronous trap procedures and signals, see REF * ASYNC sys_timer(ast_p, flags) -> usecs_or_false [procedure] sys_timer(ast_p) -> usecs_or_false usecs_or_false -> sys_timer(ast_p, flags) usecs_or_false -> sys_timer(ast_p) This procedure and its updater provide multiple real or `virtual' interval timers, each attached to a particular asynchronous trap procedure ast_p that gets run when the timer expires. (See Asynchronous Trap Procedures in REF * ASYNC for full details of the ast_p argument, which may also be a pair whose front is the procedure. Note that different timers are discriminated by == applied to the ast_p structure given; hence if a pair is supplied, the timer is attached to the pair, not to the procedure. If you supply the ASTP_ERROR_DELETE flag with ast_p, the timer is cancelled by a mishap or setpop.) The updater sets a timer going for usecs microseconds which will execute ast_p when it expires (asynchronously, i.e. inside whatever procedures the system is currently executing). Any current timer running for ast_p is first cancelled. Unless the TIMER_REPEAT bit is set in the flags argument (see below), the timer setting is one-shot, i.e. is not reset when it expires (ast_p can set another timer for itself if required). usecs may be a biginteger, the largest time allowed being pop_max_int seconds plus 999999 microseconds (i.e. the seconds part of usecs must be within the range of a simple integer). The smallest time allowed is 0, but assigning a non-zero time value smaller than the resolution of the system clock sets a timer for that resolution (e.g. 1/100th second on VAXen and Sun-4 systems, 1/50th sec on MC68000 systems, etc). A zero time value causes the timer to expire immediately. Assigning false instead of usecs cancels any current timer for ast_p. The base procedure returns the number of microseconds usecs remaining on the timer for ast_p, or false if no timer is running for it. The optional flags argument is an integer whose bits control various aspects of the timer; symbolic names for these bits are defined in INCLUDE * AST. Currently, they are: TIMER_VIRTUAL (Updater only, ignored by base procedure) If set, then the timer runs in process "virtual" time instead of real time, i.e. it runs only while the Poplog process is executing code, and not during wait states or when swapped out (or in Unix, while operating system calls are being executed). TIMER_CANCEL (Base only, ignored by updater) If set, then getting the time remaining on a timer will simultaneously cancel it. TIMER_REPEAT (Updater only, ignored by base procedure) If set, then instead of being one-shot the timer will continue to repeat every usecs microseconds until cancelled. (I.e, if the current time is T then the timer is set to fire at times T+usecs, T+2*usecs, T+3*usecs, ... etc.) (N.B. Using this flag is generally not appropriate for a virtual timer, since this will cause the execution time of the handler itself to be included in the interval usecs, i.e. the next timer will be running during the execution of ast_p for the previous one. A virtual timer should therefore reset itself at the end; this (in effect) stops the timer while the handler is running.) If the flags argument is omitted, all bits default to 0. For example, to set a 5-second (real) timer which prints a message and resets itself: define timer_trap(); "hello" => 5e6 -> sys_timer(timer_trap) ;;; 1e6 = 1 sec in usec enddefine; 5e6 -> sys_timer(timer_trap); ;;; start it off ** hello ** hello Note that currently, space is allowed for upto 32 timers running together at any one time. syssleep(hsecs) [procedure] Waits (with syshibernate) until hsecs hundredths of a second have elapsed (for which it uses a real timer set by sys_timer). syshibernate() [procedure] Suspends the current Poplog process awaiting some form of interrupt caused by an asynchronous trap or signal firing (e.g. a timer trap set by sys_timer, a SIG_INT caused by Ctrl-C typed on the terminal, or (when X is running) an X event, etc). After the interrupting event has been processed (and providing it does not cause an abnormal exit), the call of syshibernate returns. The usual way for a program to wait for a particular condition of interest, processing asynchronous events in the meantime, is therefore until condition do syshibernate() enduntil; +-+ C.all/ref/times +-+ Copyright University of Sussex 1994. All rights reserved.