generic/general/tm_time.h

/*  ASCEND modelling environment
    Copyright (C) 1997 Carnegie Mellon University
    Copyright (C) 2006 Carnegie Mellon University

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2, or (at your option)
    any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.
*//**
    @file
    Time module

    Provide a function to monitor elapsed time during the
    course of execution of a program and standard ANSI
    primitives for performing calendar calculations.

    @TODO (Apology) We apologize for the existence of this file and for
    its name being the same as an ANSI C header which is not
    consistently available, unfortunately. We really
    ought not to need this header.

    06/90 - original version
    08/93 - removed CLOCKS_PER_SECOND which should be
            provided by the standard library, eliminated
            tm_TPS and changed tm_run_time() and
            tm_cpu_time() to return number of seconds
    06/94 - eliminated cute calendar functions for full
            ANSI compatibility.

    Requires:
    #include "utilities/ascConfig.h"
*//*
    by Karl Westerberg and Joseph Zaher
    Created: 6/90
    Version: $Revision: 1.1 $
    Version control file: $RCSfile: tm_time.h,v $
    Date last modified: $Date: 2000/01/25 02:21:26 $
    Last modified by: $Author: ballan $
*/

#ifndef ASC_TM_TIME_H
#define ASC_TM_TIME_H

#include <utilities/ascConfig.h>

#ifndef CLOCKS_PER_SEC

/* case linux */
#ifdef linux
#define CLOCKS_PER_SEC  100      /**< Typical clock ticks per sec. */
#endif /* linux */

/* case windoze */
#ifdef __WIN32__
#define CLOCKS_PER_SEC 1000      /**< Typical clock ticks per sec. */
#endif /* windoze */

/* default */
#ifndef CLOCKS_PER_SEC
#define CLOCKS_PER_SEC  1000000
/**<
 *  Typical clock ticks per sec.  Note that typically clocks
 *  have a minimum resolution of 16666, sigh.
 */
#endif /* default */

#endif /* CLOCKS_PER_SEC */

ASC_DLLSPEC(double) tm_cpu_time(void);
/**<
 *  Returns elapsed CPU time in seconds since the first call
 *  to a timing function.  The timing functions that, when
 *  initially called, set the start time for all others are:
 *    - tm_cpu_time()
 *    - tm_cpu_time_ftn_()
 *    - aftime_()
 *    - tm_cpu_time_ftn()
 *    - aftime()
 *    - TM_CPU_TIME_FTN()
 *    - AFTIME()
 *
 *  Users timing portions of the process should maintain their
 *  own start time and work by difference as the solvers do.
 *
 *  @return The elapsed CPU time since the 1st call to a timing function.
 */

extern double tm_reset_cpu_time(void);
/**<
 *  Resets the start time.  Use with caution if there are
 *  multiple callers depending on a constant start time stamp.
 *  This function is primarily for testing purposes.
 *
 *  @return The initiallized elapsed CPU time.
 */

extern void tm_cpu_time_ftn_(double *time);
/**<
 *  Stores elapsed CPU time in seconds since the first call
 *  to a timing function in *t*.  The timing functions that, when
 *  initially called, set the start time for all others are:
 *    - tm_cpu_time()
 *    - tm_cpu_time_ftn_()
 *    - aftime_()
 *    - tm_cpu_time_ftn()
 *    - aftime()
 *    - TM_CPU_TIME_FTN()
 *    - AFTIME()
 *
 *  This function takes a (double *) to satisfy FORTRAN's call
 *  by reference semantics.
 *  <pre>
 *  f77 usage:  t is real*8 (double precision on most f77)
 *              external aftime, tm_cpu_time_ftn
 *              call tm_cpu_time_ftn(t)
 *              call aftime(t)
 *  </pre>
 *  On return t will have a time value (sec) stored in a double.
 *  The specified t may not be NULL (checked by assertion).<br><br>
 *
 *  If your F77 compiler doesn't morph all function calls to
 *  lower case (with or without trailing underbar), you will need
 *  to figure out its morphing convention and modify tm.[ch] so.
 *
 *  @param t Location to store the elapsed CPU time in seconds.
 */

extern void aftime_(double *time);
/**< Short name for tm_cpu_time_ftn_() to satisfy FORTRAN's 6 char restriction. */
extern void tm_cpu_time_ftn(double *time);
/**< Variant of tm_cpu_time_ftn_(). */
extern void aftime(double *time);
/**< Short name for tm_cpu_time_ftn() to satisfy FORTRAN's 6 char restriction. */
extern void TM_CPU_TIME_FTN(double *time);
/**< Variant of tm_cpu_time_ftn_(). */
extern void AFTIME(double *time);
/**< Short name for TM_CPU_TIME_FTN() to satisfy FORTRAN's 6 char restriction. */

#endif  /* ASC_TM_TIME_H */

1	/* ASCEND modelling environment
2	Copyright (C) 1997 Carnegie Mellon University
3	Copyright (C) 2006 Carnegie Mellon University
4
5	This program is free software; you can redistribute it and/or modify
6	it under the terms of the GNU General Public License as published by
7	the Free Software Foundation; either version 2, or (at your option)
8	any later version.
9
10	This program is distributed in the hope that it will be useful,
11	but WITHOUT ANY WARRANTY; without even the implied warranty of
12	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13	GNU General Public License for more details.
14
15	You should have received a copy of the GNU General Public License
16	along with this program; if not, write to the Free Software
17	Foundation, Inc., 59 Temple Place - Suite 330,
18	Boston, MA 02111-1307, USA.
19	//*
20	@file
21	Time module
22
23	Provide a function to monitor elapsed time during the
24	course of execution of a program and standard ANSI
25	primitives for performing calendar calculations.
26
27	@TODO (Apology) We apologize for the existence of this file and for
28	its name being the same as an ANSI C header which is not
29	consistently available, unfortunately. We really
30	ought not to need this header.
31
32	06/90 - original version
33	08/93 - removed CLOCKS_PER_SECOND which should be
34	provided by the standard library, eliminated
35	tm_TPS and changed tm_run_time() and
36	tm_cpu_time() to return number of seconds
37	06/94 - eliminated cute calendar functions for full
38	ANSI compatibility.
39
40	Requires:
41	#include "utilities/ascConfig.h"
42	//
43	by Karl Westerberg and Joseph Zaher
44	Created: 6/90
45	Version: $Revision: 1.1 $
46	Version control file: $RCSfile: tm_time.h,v $
47	Date last modified: $Date: 2000/01/25 02:21:26 $
48	Last modified by: $Author: ballan $
49	*/
50
51	#ifndef ASC_TM_TIME_H
52	#define ASC_TM_TIME_H
53
54	#include <utilities/ascConfig.h>
55
56	#ifndef CLOCKS_PER_SEC
57
58	/* case linux */
59	#ifdef linux
60	#define CLOCKS_PER_SEC 100 /*< Typical clock ticks per sec. /
61	#endif /* linux */
62
63	/* case windoze */
64	#ifdef __WIN32__
65	#define CLOCKS_PER_SEC 1000 /*< Typical clock ticks per sec. /
66	#endif /* windoze */
67
68	/* default */
69	#ifndef CLOCKS_PER_SEC
70	#define CLOCKS_PER_SEC 1000000
71	/**<
72	* Typical clock ticks per sec. Note that typically clocks
73	* have a minimum resolution of 16666, sigh.
74	*/
75	#endif /* default */
76
77	#endif /* CLOCKS_PER_SEC */
78
79	ASC_DLLSPEC(double) tm_cpu_time(void);
80	/**<
81	* Returns elapsed CPU time in seconds since the first call
82	* to a timing function. The timing functions that, when
83	* initially called, set the start time for all others are:
84	* - tm_cpu_time()
85	* - tm_cpu_time_ftn_()
86	* - aftime_()
87	* - tm_cpu_time_ftn()
88	* - aftime()
89	* - TM_CPU_TIME_FTN()
90	* - AFTIME()
91	*
92	* Users timing portions of the process should maintain their
93	* own start time and work by difference as the solvers do.
94	*
95	* @return The elapsed CPU time since the 1st call to a timing function.
96	*/
97
98	extern double tm_reset_cpu_time(void);
99	/**<
100	* Resets the start time. Use with caution if there are
101	* multiple callers depending on a constant start time stamp.
102	* This function is primarily for testing purposes.
103	*
104	* @return The initiallized elapsed CPU time.
105	*/
106
107	extern void tm_cpu_time_ftn_(double *time);
108	/**<
109	* Stores elapsed CPU time in seconds since the first call
110	* to a timing function in t. The timing functions that, when
111	* initially called, set the start time for all others are:
112	* - tm_cpu_time()
113	* - tm_cpu_time_ftn_()
114	* - aftime_()
115	* - tm_cpu_time_ftn()
116	* - aftime()
117	* - TM_CPU_TIME_FTN()
118	* - AFTIME()
119	*
120	* This function takes a (double *) to satisfy FORTRAN's call
121	* by reference semantics.
122	* <pre>
123	* f77 usage: t is real*8 (double precision on most f77)
124	* external aftime, tm_cpu_time_ftn
125	* call tm_cpu_time_ftn(t)
126	* call aftime(t)
127	* </pre>
128	* On return t will have a time value (sec) stored in a double.
129	* The specified t may not be NULL (checked by assertion).<br><br>
130	*
131	* If your F77 compiler doesn't morph all function calls to
132	* lower case (with or without trailing underbar), you will need
133	* to figure out its morphing convention and modify tm.[ch] so.
134	*
135	* @param t Location to store the elapsed CPU time in seconds.
136	*/
137
138	extern void aftime_(double *time);
139	/*< Short name for tm_cpu_time_ftn_() to satisfy FORTRAN's 6 char restriction. /
140	extern void tm_cpu_time_ftn(double *time);
141	/*< Variant of tm_cpu_time_ftn_(). /
142	extern void aftime(double *time);
143	/*< Short name for tm_cpu_time_ftn() to satisfy FORTRAN's 6 char restriction. /
144	extern void TM_CPU_TIME_FTN(double *time);
145	/*< Variant of tm_cpu_time_ftn_(). /
146	extern void AFTIME(double *time);
147	/*< Short name for TM_CPU_TIME_FTN() to satisfy FORTRAN's 6 char restriction. /
148
149	#endif /* ASC_TM_TIME_H */
150