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.