lib/silcutil/silctimer.h

   1 /*
   2
   3   silctimer.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2007 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SILC Timer Interface
  21  *
  22  * SILC Timer interface provides a simple way to measure time intervals.
  23  * The SILC Timer works with microsecond resolution, depending on platform.
  24  *
  25  ***/
  26
  27 #ifndef SILCTIMER_H
  28 #define SILCTIMER_H
  29
  30 /****s* silcutil/SilcTimerAPI/SilcTimer
  31  *
  32  * NAME
  33  *
  34  *    typedef struct SilcTimerObject *SilcTimer, SilcTimerStruct;
  35  *
  36  * DESCRIPTION
  37  *
  38  *    The timer context.  The context is given as argument to all
  39  *    silc_timer_* functions.
  40  *
  41  ***/
  42 typedef struct SilcTimerObject *SilcTimer, SilcTimerStruct;
  43
  44 /****f* silcutil/SilcTimerAPI/silc_timer_start
  45  *
  46  * SYNOPSIS
  47  *
  48  *    SilcBool silc_timer_start(SilcTimer timer);
  49  *
  50  * DESCRIPTION
  51  *
  52  *    Starts the timer.  If the timer is already running this will reset
  53  *    the timer and continue.
  54  *
  55  * EXAMPLE
  56  *
  57  *    SilcTimerStruct timer;
  58  *
  59  *    silc_timer_start(&timer);
  60  *    ... time passes ...
  61  *    silc_timer_stop(&timer);
  62  *    silc_timer_value(&timer, &elapsed_sec, &elapsed_usec);
  63  *
  64  ***/
  65 void silc_timer_start(SilcTimer timer);
  66
  67 /****f* silcutil/SilcTimerAPI/silc_timer_stop
  68  *
  69  * SYNOPSIS
  70  *
  71  *    void silc_timer_stop(SilcTimer timer);
  72  *
  73  * DESCRIPTION
  74  *
  75  *    Stop the timer.  The elapsed time can be retrieved by calling the
  76  *    silc_timer_value function.
  77  *
  78  ***/
  79 void silc_timer_stop(SilcTimer timer);
  80
  81 /****f* silcutil/SilcTimerAPI/silc_timer_continue
  82  *
  83  * SYNOPSIS
  84  *
  85  *    void silc_timer_continue(SilcTimer timer);
  86  *
  87  * DESCRIPTION
  88  *
  89  *    Continue stopped timer.  If timer is running already this does nothing.
  90  *
  91  ***/
  92 void silc_timer_continue(SilcTimer timer);
  93
  94 /****f* silcutil/SilcTimerAPI/silc_timer_value
  95  *
  96  * SYNOPSIS
  97  *
  98  *    void silc_timer_value(SilcTimer timer,
  99  *                          SilcUInt64 *elapsed_time_seconds,
 100  *                          SilcUInt32 *elapsed_time_microseconds);
 101  *
 102  * DESCRIPTION
 103  *
 104  *    Returns either the current value or the end value of the timer.  If the
 105  *    timer is currently running this returns the currently elapsed time.  If
 106  *    the timer is stopped this returns the cumulative elapsed time.
 107  *
 108  ***/
 109 void silc_timer_value(SilcTimer timer,
 110                       SilcUInt64 *elapsed_time_seconds,
 111                       SilcUInt32 *elapsed_time_microseconds);
 112
 113 /****f* silcutil/SilcTimerAPI/silc_timer_value_time
 114  *
 115  * SYNOPSIS
 116  *
 117  *    void silc_timer_value_time(SilcTimer timer, SilcTime ret_time);
 118  *
 119  * DESCRIPTION
 120  *
 121  *    Same as silc_timer_value but returns the elapsed time to `ret_time'
 122  *    SilcTime structure as absolute date and time.  This is useful if the
 123  *    returned time needs to be converted into some other format such as
 124  *    time and date strings.
 125  *
 126  ***/
 127 void silc_timer_value_time(SilcTimer timer, SilcTime ret_time);
 128
 129 /****f* silcutil/SilcTimerAPI/silc_timer_start_time
 130  *
 131  * SYNOPSIS
 132  *
 133  *    void silc_timer_start_time(SilcTimer timer, SilcTime ret_start_time);
 134  *
 135  * DESCRIPTION
 136  *
 137  *    Returns the timer's start time into `ret_start_time' SilcTime structure.
 138  *
 139  ***/
 140 void silc_timer_start_time(SilcTimer timer, SilcTime ret_start_time);
 141
 142 /****f* silcutil/SilcTimerAPI/silc_timer_is_running
 143  *
 144  * SYNOPSIS
 145  *
 146  *    SilcBool silc_timer_is_running(SilcTimer timer);
 147  *
 148  * DESCRIPTION
 149  *
 150  *    Returns TRUE if the timer is currently running, FALSE otherwise.
 151  *
 152  ***/
 153 SilcBool silc_timer_is_running(SilcTimer timer);
 154
 155 #include "silctimer_i.h"
 156
 157 #endif /* SILCTIMER_H */