1/*---------------------------------------------------------------------------*
2 *  ptimer.h  *
3 *                                                                           *
4 *  Copyright 2007, 2008 Nuance Communciations, Inc.                               *
5 *                                                                           *
6 *  Licensed under the Apache License, Version 2.0 (the 'License');          *
7 *  you may not use this file except in compliance with the License.         *
8 *                                                                           *
9 *  You may obtain a copy of the License at                                  *
10 *      http://www.apache.org/licenses/LICENSE-2.0                           *
11 *                                                                           *
12 *  Unless required by applicable law or agreed to in writing, software      *
13 *  distributed under the License is distributed on an 'AS IS' BASIS,        *
14 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
15 *  See the License for the specific language governing permissions and      *
16 *  limitations under the License.                                           *
17 *                                                                           *
18 *---------------------------------------------------------------------------*/
19
20#ifndef PTIMER_H
21#define PTIMER_H
22
23
24
25#include "PortPrefix.h"
26#include "ptypes.h"
27
28/**
29 * @addtogroup PTimerModule PTimer API functions
30 * API to facilitate computing elapsed time of operations.  The units of time
31 * are milliseconds.
32 *
33 * @{
34 */
35
36/** Typedef */
37typedef struct PTimer_t PTimer;
38
39/**
40 * Creates a new timer object.
41 *
42 * @param timer PTimer handle.
43 */
44PORTABLE_API ESR_ReturnCode PTimerCreate(PTimer **timer);
45
46/**
47 * Destroys the timer object.
48 *
49 * @param timer PTimer handle.
50 */
51PORTABLE_API ESR_ReturnCode PTimerDestroy(PTimer *timer);
52
53/**
54 * Starts the timer. This sets the reference time from which all new elapsed
55 * time are computed.  This does not reset the elapsed time to 0.  This is
56 * useful to pause the timer.
57 **/
58PORTABLE_API ESR_ReturnCode PTimerStart(PTimer *timer);
59
60/**
61 * Stops the timer.
62 **/
63PORTABLE_API ESR_ReturnCode PTimerStop(PTimer *timer);
64
65/**
66 * Returns the timer elapsed time.  If the Timer is in the stopped state,
67 * successive calls to getElapsed() will always return the same value.  If the
68 * Timer is in the started state, successive calls will return the elapsed
69 * time since the last time PTimerStart() was called.
70 */
71PORTABLE_API ESR_ReturnCode PTimerGetElapsed(PTimer *timer,
72    asr_uint32_t *elapsed);
73
74/**
75 * Resets the elapsed time to 0 and resets the reference time of the Timer.
76 * This effectively reset the timer in the same state it was right after
77 * creation.
78 **/
79PORTABLE_API ESR_ReturnCode PTimerReset(PTimer *timer);
80
81/**
82 * @}
83 */
84
85
86#endif
87