Index | PAL Intro | Commands | Registers | Indices | Stack | Macros | Classes | Attributes | Errors

ps_time - Introduction to PROSE time module

CONTENTS

Description
System Timer
Sleeping
See Also
Author

Support for time, including timers and time calculations in PROSE, is provided by the ps_time module.

The ps_time module provides a number of different time-related features which are discussed below, including:

o Time format using generalizedTime syntax (RFC4517) o Time-based calculations o System timer using the realtime clock.

The psTime variable is used to store time format in PROSE. It represents the number of seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC), stored as a 128-bit floating point number allowing for nanosecond precision and it records a separate timezone offset as a positive or negative integer.

A psTime variable is typically initialised with var/def or one of its associated instructions. The initialisation value may be either:

String	A string containing a time in LDAP generalizedTime format according to RFC4517 or a string representation of the number of seconds since the Epoch as an integer or a floating point number.
Index	A 32-bit unsigned integer (psIndex) representing the number of whole seconds since the Epoch. Using an index to initialise a psTime may have some limited applications although care should be taken not to attempt to represent years beyond 2106 while in this format.

When comparing psTime variables for equality or numerical ordering, the timezone is ignored. That is, the comparison is made according to UTC. This would mean, for example, that 20171027221200+0100 and 20171027171200-0400 would be considered equal.

The following mathematical operations will also work correctly on psTime variables and operate on the UTC time disregarding the timezone:

o Increment by one second o Decrement by one second o Add, subtract, multiply and divide.

The operand when adding, subtracting, multiplying or dividing may be another psTime variable, a 32-bit unsigned integer (psIndex), a GMP integer (psInteger), a GMP float (psFloat) or a string representation of any of these formats.

An object with the psTime class also has available the following virtual attributes that may be read or modified and will change the psTime attribute accordingly:

psTimeSeconds
	Number of seconds since the epoch (1 January 1970). This behaves as a psFloat.
psTimezoneOffset
	Timezone offset from UTC in HHMM format represented as a psInteger. The accepted range is -2359 to 2359.

The .prose.sys.timer node provides two views of the system’s realtime clock, accessed via the following virtual attributes assigned to the object:

psTimerSeconds
	obtains the current value as a whole number of seconds using clock_gettime(2) with CLOCK_REALTIME.
psTimerSecondsPrecise
	obtains the current value as a 128-bit precision floating point number using clock_gettime(2) with CLOCK_REALTIME.

The main purpose of the system timer is to allow a program to accurately determine how much time has elapsed between two events under its control. It is not guaranteed that psTimerSeconds and psTimerSecondsPrecise will be implemented as a view of the realtime clock in the future, nor that it will be implemented the same way on every platform. The system timer should only be used for determining elapsed time by comparing two values obtained through it at two different moments in time. In future releases it may be changed so that whenever you first get a reference to the node the counter starts from zero.

SLEEPING

The .prose.sys.timer node may also have the psSleepSeconds attribute assigned to it which will immediately cause the program to pause for the specified number of seconds with nanosleep(2). The value passed to this attribute may be a 128-bit precision floating point number.

pal_intro(5), pal_commands(5), pal_registers(5), pal_indices(5), ps_classes(5), ps_attributes(5), ps_errortypes(5), var_def(5), clock_gettime(2), nanosleep(2),
PROSE Assembly Language at prose.sourceforge.net.

Copyright (c) 2002-2017 Mark R. Bannister <cambridge@users.sourceforge.net>.

This is free software and can be downloaded from prose.sourceforge.net; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.