README

                             LIBFASTTIME


!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
This was open sourced before I expected. Much of the work was done
half a year ago and still has rough edges from what I remember,
specifically around gettimeofday(). The test code is also quite messy.
Please spend some time verifying behavior before putting in
production. Improvements will be eagerly accepted.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Fast time calls from user space.

SUMMARY

    Overrides several time-related system library functions, providing
    the same functionality without incurring the syscall penalty. It
    is meant for applications with tight loops on time calls such as
    gettimeofday(3C) and clock_gettime(3C), requiring latency of tens
    of nanoseconds.

OVERRIDDEN FUNCTIONS

    * gettimeofday(3C) -- Get wall clock time as period of seconds +
      microseconds since Unix epoch.

    * clock_gettime(3C) -- POSIX API providing access to several
      different types of clocks.

      - CLOCK_REALTIME -- System-wide wall clock as period of seconds
        + nanoseconds since Unix epoch.

      - CLOCK_MONOTONIC -- System-wide clock relative to some
        arbitrary point in time, only moves forward, and is not
        affected by system time changes.

    * gethrtime(3C) -- System-wide clock relative to some arbitrary
      point in time and is not affected by system time changes. Only
      available on illumos.

CAVEATS

    * All functions are built on the CPU's TSC register. To provide
      the expected latency no fencing (LFENCE) or synchronization
      (CPUID/RDTSCP) is done. Out-of-order execution is free to
      rearrange these calls with its surrounding instructions. This is
      probably acceptable for the library's intended purpose. It would
      be a different story if used for precise cycle count in
      microbenchmarks.

INSTALL

    CentOS 6.6

        # yum install gcc glibc-devel.i686 libgcc-4.4.7-11.el6.i686 libstdc++-devel.i686
        # make
        # make test
        # make install

USAGE

    There are three different ways to link libfasttime to your
    program.

    1) Link to an individual program at compile time via the -L and -l
       linker flags.

        Linux:

                gcc -m64 -L/opt/lucera/lib64 -lfasttime \
                    -Wl,-rpath,/opt/lucera/lib64 -o my_program my_program.c

    2) Link to an individual program at runtime via the LD_PRELOAD
       environment variable.

        Linux:

                LD_PRELOAD=/opt/lucera/\${LIB}/libfasttime.so my_program

    3) Link to all programs at runtime.

        Linux:

                Uncomment line in /etc/ld.so.preload.