OpenRM - RM Library (rmtime.c)

## Index of OpenRM - RM Library

     RMenum rmTimeCurrent (RMtime *result)

     RMtime *result - a handle to a caller-supplied RMtime struct.

Time measurement in RM is performed by querying the time with rmTimeCurrent(), by computing time difference with rmTimeDifference(), or computing the elapsed time in milliseconds with rmTimeDifferenceMS().

rmTimeCurrent() will initialize an RMtime object, which is essentially the same as a "struct timeval" on Unix systems, with the current time. The caller supplies a handle to an RMtime object, and it will be set to contain the current time. Time zones are not relevant, as the purpose of RM's timing facilities is limited to taking millisecond-resolution measurements of time. RM_CHILL is returned upon success, or RM_WHACKED upon failure.

rmTimeDifference() takes two RMtimeVal objects that have been set with rmTimeCurrent(), computes the difference in time between the two, and places the difference into a third RMtime object. RM_CHILL is returned upon success, or RM_WHACKED upon failure.

rmTimeDifferenceMS() takes two RMtime objects that have been set with rmTimeCurrent(), and returns the difference in milliseconds between the two.

rmTimeSet() allows you to set the secs/usecs fields of the RMtime object to specific values. rmTimeGet() will tell you what those values are.

rmTimeSleep() implements a spinlock high-resolution delay function that will block the caller for the amount of time (secs, usecs) specified in the input RMtime object.

rmTimeDecodeMS() will return a double value representing the number of milliseconds represented by the values in the input RMtime object. rmTimeEncodeMS() will accept a double value interpreted as milliseconds and encode that information into an RMtime object.

rmTimeNew() and rmTimeDelete() are used to create and destroy RMtime objects, respectively.

librm library source file: rmtime.c

     RMenum rmTimeDifference (const RMtime *start, const RMtime *end, RMtime *result)

     const RMtime *start, *end - handles to caller-supplied RMtime structs
     that contain valid time values.
     RMtime *result - a handle to a caler-supplied RMtime struct. This
     value will be computed as the difference between "start" and "end."

Time measurement in RM is performed by querying the time with rmTimeCurrent(), by computing time difference with rmTimeDifference(), or computing the elapsed time in milliseconds with rmTimeDifferenceMS().

rmTimeDifference() takes as input two RMtime objects, start and end, and computes the difference between them. The result is placed into the "result" RMtime object.

Limitations: it is assumed that time in "end" is later than the value in "start." If this assumption doesn't hold, then the computed difference may not be accurate.

librm library source file: rmtime.c

     double rmTimeDifferenceMS (const RMtime *start, const RMtime *end)

     const RMtime *start, *end - handles to caller-supplied RMtime structs
     that contain valid time values.

Time measurement in RM is performed by querying the time with rmTimeCurrent(), by computing time differences with rmTimeDifference(), and by reporting the time difference in milliseconds with rmTimeDifferenceMS().

rmTimeDifferenceMS() takes two RMtimeVal objects that have been set with rmTimeCurrent(), computes the difference in time between the two, and returns a double precision value indicating the number of milliseconds difference between the two RMtime objects.

It is assumed that the time value in "end" is greater than or equal to the time value in "start." If this assumption does not hold, the computed and returned difference may be inaccurate.

Upon success, a non-negative integer is returned. Upon failure, -1 is returned. If the time value in "end" is less than the time value in "start", the returned value is not guaranteed to be accurate. It is the application's responsibility to ensure the timevalue in "end" is greater than or equal to the time value in "start".

librm library source file: rmtime.c

     RMtime * rmTimeNew(void)

     No arguments.

rmTimeNew() will create an RMtime object, and return the handle of the new RMtime object to the caller upon success. Upon failure, NULL is returned.

No special processing is performed inside rmTimeNew(). It is safe for applications to allocate RMtime objects off the stack using normal variable declaration if so desired.

librm library source file: rmtime.c

     RMenum rmTimeDelete(RMtime *toDelete)

     RMtime *toDelete - handle to an RMtime object that will be deleted.

This routine will free resources associated with the input RMtime object "toDelete." Upon success, RM_CHILL is returned. Upon failure, RM_WHACKED is returned.

librm library source file: rmtime.c

     RMenum rmTimeSet(RMtime *toModify, long secs, long usecs)

     long secs, usecs: input arguments specifing number of seconds and
     microseconds, respectively.

rmTimeSet is used to assign known values to the RMtime object "toModify." The RMtime object contains two fields - seconds and microseconds. When set by rmTimeCurrent(), those values represent the amount of time elapsed since the current epoch.

(Note that since we use longs, OpenRM is Y2038 safe!!)

Upon success, RM_CHILL is returned. Upon failure, RM_WHACKED is returned.

Limitations: OpenRM doesn't perform any sanity checking on the input values for secs/usecs. It is possible to assign garbage to an RMtime object.

librm library source file: rmtime.c

     RMenum rmTimeGet(const RMtime *toQuery, long *returnSecs, long *returnUSecs)

     const RMtime *toQuery - an input RMtime object.
     long *returnSecs, long *returnUSecs - pointers to longs.

rmTimeGet() will copy the seconds/microseconds fields from the input RMtime object "toQuery" into the memory pointed to by "returnSecs" and "returnUSecs."

If you just want to know the number of milliseconds contained in an RMtime representation, use the routine rmTimeDecodsMS().

RM_CHILL is returned upon success, or RM_WHACKED upon failure.

librm library source file: rmtime.c

     RMenum rmTimeSleep(const RMtime *toSleep)

     RMtime *toSleep - input RMtime object that specifies the length of the
     sleep period.

rmTimeSleep() will block execution of the caller for the amount of time specified in the toSleep argument. This routine will block execution for a period of time that is at least as long as the time specified in the toSleep object. In our preliminary testing, we have found the error to be quite small - less than a microsecond on current hardware.

Internally, a high-resolution spinlock is used to implement precision naps. There is a large body of knowledge on the subject of problems with precision sleeps. The brute-force solution is to use a spinlock, which is what we do here. The two primary advantages of the spinlock are: (1) they are of a very high resolution, and (2) the time required to wake up from a nap is less likely to be interruped or influenced by the OS doing something else, like checking to see if the printer is awake.

Since we use a spinlock, your CPU meter will be pegged at 100% during rmTimeSleep naps.

This routine returns RM_CHILL upon success, or RM_WHACKED upon failure.

librm library source file: rmtime.c

     RMenum rmTimeEncodeMS(RMtime *toModify, double ms)

     RMtime *toModify - input RMtime object to be modified.
     double ms - double precision value interpreted as milliseconds.

rmTimeEncodeMS() will take an input double precision value that is interpreted as milliseconds, and encode the number of milliseconds (that may be fractional) into the RMtime object.

RM_CHILL is returned upon success, and RM_WHACKED is returned upon failure.

librm library source file: rmtime.c

     RMenum rmTimeDecodeMS(const RMtime *toQuery, double *resultMS)

     const RMtime *toQuery - an input RMtime object.
     double *resultMS - a pointer to a double precision value; the results of
       this routine will be returned in this caller-supplied memory.

rmTimeDecodeMS will compute the number of milliseconds represented by the contents of the input RMtime object toQuery, and return the results into caller supplied memory.

RM_CHILL is returned upon success, and RM_WHACKED is returned upon failure.

librm library source file: rmtime.c