Access Local Time

Data Structures
struct	MICRO

Macros
#define	current_msec()   current_time()

Typedefs
typedef enum _EL_CLOCK_BASE	EL_CLOCK_BASE
	Enum used to configure the behaviour of the time functions.

Enumerations
enum	_EL_CLOCK_BASE { SR_CLOCK_BASE_APPLICATION_LOCAL =0, SR_CLOCK_BASE_MACHINE_LOCAL =1 }
	Enum used to configure the behaviour of the time functions. More...

Functions
void	eyelink_set_clock_base (EL_CLOCK_BASE clock_base)
EL_CLOCK_BASE	eyelink_get_clock_base (void)
UINT32	current_time (void)
UINT32	current_micro (MICRO FARTYPE *m)
UINT32	current_usec (void)
void	msec_delay (UINT32 n)
double	current_double_usec (void)
INT16	eyelink_reset_clock (INT16 enable)

Detailed Description

These functions are used to access display time

Macro Definition Documentation

#define current_msec

(

)

current_time()

See current_time()

Enumeration Type Documentation

enum _EL_CLOCK_BASE

Enum used to configure the behaviour of the time functions.

Enumerator
SR_CLOCK_BASE_APPLICATION_LOCAL	SR_CLOCK_BASE_APPLICATION_LOCAL is the default. The time stamp starts from the beginning of the application. Reading this time across multiple application on the same computer will not provide meaningful result as the time bases are different.
SR_CLOCK_BASE_MACHINE_LOCAL	The time stamp starts from the boot time of the machine or a random point. Reading this time across multiple applications will give comparable time. This selection is useful, when you have multiple applications that save data or send messages to the tracker with a local time stamp. Remarks This selection may lead to premature clock roll over.

Function Documentation

double current_double_usec

(

void

)

Returns the current microsecond as double (56 bits) since the initialization. Equivalent to current_micro() and current_usec().

Returns

The current microsecond as a double value since the initialization of the library, modulo 2^32.

Example: See current_usec()

\sa \c current_micro(), \c current_usec(), \c current_msec(), \c current_time() and \c msec_delay()

UINT32 current_micro

(

MICRO FARTYPE *

m

)

Returns the current microsecond since the initialization. Equivalent to current_usec() and current_double_usec().

Parameters

m	Pointer to MICRO structure.

Returns

The current microsecond since the initialization of the library, modulo 2^32. It can also fill in the MICRO structure if the pointer is not NULL.

Example: See current_usec()

See also

current_usec(), current_double_usec(), current_msec(), current_time() and msec_delay()

UINT32 current_time

(

void

)

Returns the current millisecond since the initialization.

Remarks

If the eyelink_exptkit library is not initialized, or initialized multiple times, the return value is invalid and the return value is unpredictable. So in order to avoid this, make sure that close_eyelink_system() is called at the end. The call to current_msec() is always equivalent to current_time().

Returns

The current millisecond since the initialization of the library.

Example:

// This program illustrates the use of current_msec
#include <eyelink.h>
#include <stdio.h>

eyemsg_printf("Delay test starts: %ld", current_msec());
msec_delay(100);
eyemsg_printf("Delay test ends: %ld", current_time());

Output:

MSG 4532575 Delay test starts: 5236
MSG 4532671 Delay test ends: 5336

See also

current_msec(), current_micro(), current_usec(), eyelink_tracker_time() and msec_delay()

UINT32 current_usec

(

void

)

Returns the current microsecond since the initialization. Equivalent to current_micro() and current_double_usec().

Remarks

If the eyelink_exptkit library is not initialized, or initialized multiple times, the return value is invalid and unpredictable. The call to current_usec() is equivalent to current_micro(NULL). The function is very platform dependent. Platforms such as windows 95, 98, ME may not return usec properly. Ie. It may return current_time() * 1000.

Returns

The current microsecond since the initialization of the library, modulo 2^32.

Example:

// This program illustrates the use of current_micro and current_usec

#include <eyelink.h>
#include <stdio.h>

MICRO m1, m2;  // Special high-resolution time structure

// Get the current subject PC time in microseconds
current_micro(&m1);
eyemsg_printf("Delay test starts: %ld", current_usec());

// Delay for 100 msec
msec_delay(100);

// Get the current subject PC time again
current_micro(&m2);
eyemsg_printf("Delay test ends: %ld", current_usec());

// Calculate the actual amount of delay
eyemsg_printf("Total Delay: %6.3f",
    m2.msec + m2.usec/1000.0 - m1.msec + m1.usec/1000.0);

Output:

MSG 5441107 Delay test starts: 4610094
MSG 5441206 Delay test ends: 4710005
MSG 5441206 Total Delay: 100.003

See also

current_micro(), current_double_usec(), current_msec(), current_time() and msec_delay()

EL_CLOCK_BASE eyelink_get_clock_base

(

void

)

Returns the clock base for the local time access.

Returns

returns the current time base.

See also

current_msec(), current_micro(), current_usec(), eyelink_tracker_time() and msec_delay()

eyelink_set_clock_base

INT16 eyelink_reset_clock

(

INT16

enable

)

Initializes the high frequency clock.

With TSR interface under msdos, Start/stop timing resources.

Parameters

enable

Usually <enable> is 1. However, in MS-DOS passing 0 will cleanup the timing resources. In other platforms passing 0 has no effect.

void eyelink_set_clock_base

(

EL_CLOCK_BASE

clock_base

)

Sets the clock base for the local time access. This changes the behaviour of the time functions.

eg.

   eyelink_set_clock_base(SR_CLOCK_BASE_MACHINE_LOCAL);
   if(open_eyelink_connection(-1) !=0) // connect to the tracker
{
      printf("Failed to connect to tracker \n");
      return 0;
}
printf("Time=%.2f \n",current_double_usec()/1000.0);

Output:

Time=21056627.66

Now look at the difference in the output where the first call to current_double_usec() returns much smaller value when the time base is SR_CLOCK_BASE_APPLICATION_LOCAL

   //eyelink_set_clock_base(SR_CLOCK_BASE_MACHINE_LOCAL);
   //commenting out eyelink_set_clock_base is the same as
   //calling eyelink_set_clock_base(SR_CLOCK_BASE_APPLICATION_LOCAL);
   if(open_eyelink_connection(-1) !=0) // connect to the tracker
{
      printf("Failed to connect to tracker \n");
      return 0;
}
printf("Time=%.2f \n",current_double_usec()/1000.0);

Output:

Time=0.07

Remarks

SR_CLOCK_BASE_MACHINE_LOCAL may lead to premature clock roll over.

This needs to be called before any of the time initializations. The time initialization is done on first time function call or on first open_eyelink_connection().

Example:

// This program illustrates the use of eyelink_set_clock_base
eyelink_set_clock_base(SR_CLOCK_BASE_MACHINE_LOCAL);
if(open_eyelink_connection(-1) !=0) // connect to the tracker
{
    printf("Failed to connect to tracker \n");
    return 0;
}

for(i=0; i < 20; i++)
{
    now =current_time();
    printf("%s Time %ld %.2f time=%.2f days time_to_rollover=%.2f days\n",argv[1], now, current_double_usec()/1000.0, ((double)(now))/(1000.0*60*60*24), ((double)(end-now))/(1000.0*60*60*24));
    usleep(2000000);
}

Output: when executing multiple instance of the above program

1 Time 137271197 137271197.83 time=1.59 days time_to_rollover=48.12 days
3 Time 137271228 137271228.09 time=1.59 days time_to_rollover=48.12 days
2 Time 137272211 137272211.46 time=1.59 days time_to_rollover=48.12 days
4 Time 137272239 137272239.68 time=1.59 days time_to_rollover=48.12 days
3 Time 137273229 137273229.08 time=1.59 days time_to_rollover=48.12 days
4 Time 137274240 137274240.79 time=1.59 days time_to_rollover=48.12 days

See also

current_msec(), current_micro(), current_usec(), eyelink_tracker_time() and msec_delay() eyelink_get_clock_base

void msec_delay

(

UINT32

n

)

Does a unblocked delay using current_time().

Parameters

n	n milliseconds to delay.

Example:

// This program illustrates the use of msec_delay
#include <eyelink.h>
#include <stdio.h>

eyemsg_printf("Delay test starts: %ld", current_msec());
// delay for 100 msec
msec_delay(100);
eyemsg_printf("Delay test ends: %ld", current_time());

Output:

MSG 4346690 Delay test starts: 12768
MSG 4346791 Delay test ends: 12868

See also

current_msec() and pump_delay()