StartInterval [LJM User's Guide]

Sets up a reoccurring interval timer based on the host clock.

Syntax

LJM_ERROR_RETURN LJM_StartInterval(
int IntervalHandle,
int Microseconds)

Parameters

IntervalHandle [in]

The user-generated interval identifier. This can be anything.

Microseconds [in]

The number of microseconds in the interval.

Returns

LJM errorcodes or 0 for no error.

Remarks

This function allocates memory for the given IntervalHandle and begins a reoccurring interval timer. This function does not perform any waiting.

Interval Timer vs Delay

In many applications an interval timer is preferable to using a normal delay (sleep) because it is difficult to get an exact interval using a delay. For example, say a loop makes an I/O call that takes 5 to 15 milliseconds (ms) each time, and this is followed by a 90 ms delay. The loop will take 95 to 105 ms per iteration, and the average time per iteration over time could be anywhere in that range. Using interval timers avoids this problem because the loop will always take the specified number of milliseconds—or else LJM_WaitForNextInterval will report skipped intervals.

Clock jitter and clock skew may occur, but the average interval period over time will be equal to the number of specified Microseconds, ignoring skipped intervals.

Clock Sources

There are three categories of clocks:

Host clocks: LJM_StartInterval allows for steady clock or system clock.
Device clock: For precise, hardware-based timing, use Lua scripting or streaming. Streaming does not incur clock jitter.
Sync clocks: See externally-clocked stream.

Steady Clock vs System Clock

The LJM_INTERVAL_CLOCK_TYPE configuration sets which type of host clock LJM_StartInterval initializes:

Steady clock (default): The steady clock is not affected by Network Time Protocol (NTP) updates or updates to the system clock.
System clock: Also known as the wall clock, the system clock can jump forward or backward. This can happen due to NTP updates or due to manually setting the system clock.

See LJM_INTERVAL_CLOCK_TYPE for details.

Example

Given a handle to a device, a function named ReadAndOutput that reads and outputs a registers, and an error-checking function called ErrorCheck, the following example reads AIN0 once per second, 100 times:

Read AIN0 once per second, 100 times.

C

int err;
int SkippedIntervals;
const int INTERVAL_HANDLE = 1;
err = LJM_StartInterval(INTERVAL_HANDLE, 1000 * 1000);
ErrorCheck(err, "LJM_StartInterval");

for (int loop = 0; loop < 100; loop++) {
    ReadAndOutput(handle, "AIN0");

    err = LJM_WaitForNextInterval(INTERVAL_HANDLE, &SkippedIntervals);
    ErrorCheck(err, "LJM_WaitForNextInterval");
    if (SkippedIntervals > 0) {
        printf("SkippedIntervals: %d\n", SkippedIntervals);
    }
}

err = LJM_CleanInterval(INTERVAL_HANDLE);
ErrorCheck(err, "LJM_CleanInterval");