EpikTimer: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		### About
2	2
3	3		EpikTimer is a programmer's stopwatch that is capable of measuring very short events with traceably high precision over long periods of time. It's simple to use, consumes virtually no CPU and requires only 25 bytes of ram to implement a timer instance. The component provides a single internal timer... but unlimited numbers can be declared externally and linked to a single EpikTimer component on the form.
4	4
5	5		The download contains the component, an installation package and a demo application, that illustrates the features of the component along with some instrumentation for evaluating the clock sources on a given system.
6	6
7	7		This component was designed for cross-platform applications and was written specifically for the Lazarus IDE and Free Pascal Compiler and includes a demo application.
8	8
9	9		### Author
10	10
11	11		Tom Lisjac
12	12
13	13		### License
14	14
15	15		[LGPL](http://www.opensource.org/licenses/lgpl-license.php) (please contact the author if the LGPL doesn't work with your project licensing)
16	16
17	17		### Download
18	18
19	19		The source code can be downloaded from the Git repository as follows:
20	20
21		-	~~` git clone `[`https://github.com/graemeg/epiktimer.git`](https://github.com/graemeg/epiktimer.git)~~
	21	+	```text
	22	+	git clone https://github.com/graemeg/epiktimer.git
	23	+	```
22	24
23	25		If you don't want to install a Git client, Github also allows you to download the latest code as a ZIP archive. Simply go to the [Github EpikTimer](https://github.com/graemeg/epiktimer) url and click the "Download ZIP" button on the right.
24	26
25	27		All tagged releases can be downloaded in .zip or .tar.gz format by going to this [Github Releases](https://github.com/graemeg/epiktimer/releases) url and select the zip or tar.gz link for whichever release you want to download.
26	28
27	29		### Project Status
28	30
29	31		- Production/Stable
30	32
31	33		### Change Log
32	34
33	35		- Initially written on 24-06-2003 TL
34	36		- Pre-release 30-06-2003 TL - Needs testing on the BSD's and Win32
35	37		- Version 0.1 1-7-2003 TL
36	38
37	39		1. initial beta release
38	40
39	41		- Version 0.2 3-7-2003 TL
40	42
41	43		1. Revised logic around hardware detection to prevent executing extended instructions if the HasCapabilityData call returns false.
42	44		2. Removed exposed low level diagnositic functions from unit interface.
43	45		3. Revised demo.
44	46
45	47		- Version 0.3 15-11-2005
46	48
47	49		1. Updated 0.2 version to make it compile on the latest Lazarus (0.9.10).
48	50		2. Added LCL to the required packages.
49	51		3. Changed mode to Delphi in order to compile.
50	52		4. Changed windows timebase to use QueryPerformanceCounter, because has a much greater precision then GetSystemTime.
51	53		5. Added changes to ensure the component compiles on Delphi 7.0
52	54		6. Made tests on Windows and Linux
53	55		7. Small changes to the demo to make it compile
54	56
55	57		- Version 1.0 06-10-2006
56	58
57	59		1. Changes for 64 bits operation
58	60		2. Added units BaseUnix, Unix and UnixUtil, removed oldlinux (obsolete)
59	61		3. Gettimeofday -\> fpGettimeofday
60	62		4. Changed systemsleep for 64 bits systems
61	63		5. Some changes in timeval
62	64		6. Tested on AMD64 (linux)
63	65
64	66		For any later changes, please see the Git commit log.
65	67
66	68		### Dependencies / System Requirements
67	69
68	70		- Nanosecond resolution is supported on Intel Pentium versions with a Timestamp Counter.
69	71		- Microsecond system clock is the default timebase.
70	72
71	73		Tested on:
72	74
73	75		- Pentium IV 3,2Ghz on Windows and Linux with great precision (~ 3,220,000,000 ticks per second)
74	76		- Pentium 233Mhz with Damn Small Linux. Works great with hardware clock.
75	77		- Mobile AMD 64 Athlon 3200+ on Windows XP Home (32 bit), Lazarus 9.13
76	78		- AMD 64 CPU, running 64 bit version of Ubuntu Linux, Lazarus 9.18.
77	79		- Intel i7-3770K, running 64-bit version of FreeBSD 9.1, using FPC 2.6.2
78	80		- ARM CPU using Raspberry Pi and FPC 2.6.2
79	81
80	82		### Installation in Lazarus IDE
81	83
82	84		- In Components/Open Package File, open etpackage.lpk
83	85		- Compile the package and close the package dialog
84	86		- In Components -\> Open Package File, open the etpackage_dsgn.lpk
85	87		- Compile the package.
86	88		- Click the Install button and let Lazarus rebuild
87	89		- Component will be in the System Palette (stopwatch-ruler icon)
88	90
89	91		### Usage
90	92
91	93		Drop the component on a form. The component contains a single timer instance and parameterless calls to start, stop, elapsed and clear will implicitly reference it.
92	94
93	95		If the timer is named ET
94	96
95	97		``` pascal
96	98		uses epiktimer;
97	99
98	100		var
99	101		ET: TEpikTimer;
100	102
101	103		procedure InitTimer;
102	104		begin
103	105		ET := TEpikTimer.Create(Application);
104	106		end;
105	107
106	108		procedure InstrumentedCall;
107	109		Begin
108	110		ET.Clear; // optional... timer is cleared at creation
109	111		ET.Start;
110	112		ExecuteFirstTimedSection;
111	113		ET.Stop; // the timer is actually paused and can be restarted later
112	114		TimedSection1:=ET.Elapsed; // store the elapsed in a global
113	115		MakeAnUntimedOverheadCall; // not counted in the timer
114	116		ET.Start; //resume the timer... continue accumulating ticks
115	117		CallTimedSection2;
116	118		TimedSection2:=ET.Elapsed; //timer keeps running... we've just sample it.
117	119		CallTimedSection3;
118	120		CallSomethingElse;
119	121		TimedSection3:=ET.Elapsed; //keep counting... tap the elapsed
120	122		CallTimedSection4;
121	123		TimedSection4:=ET.Elapsed; //keep counting... tap the elapsed
122	124		ET.clear // done... timer is stopped and zeroed
123	125		end;
124	126		```
125	127
126	128		You can also create any number of timers from a single component on the form by declaring a TimerData record and passing it as a parameter to start, stop, elapsed and clear using the overloaded methods in the component. An example would be:
127	129
128	130		``` pascal
129	131		Function TimedExecution: Extended;
130	132		Var
131	133		DiskAccessTime:TimerData;
132	134		Begin
133	135		ET.Clear(DiskAccessTimer); // Declared timers must be cleared before use.
134	136		ET.Start(DiskAccessTimer);
135	137		ExecuteTheTimedSection;
136	138		Result:=ET.Elapsed(DiskAccessTimer); // the timer keeps running...
137	139		etc...
138	140		```
139	141
140	142		One particular use for EpikTimer is checking if a given amount of time has elapsed before continuing with a task or to another iteration of the same task.
141	143
142	144		``` pascal
143	145		DelayInSeconds := 8.5; // or any value
144	146		OldTime := ET.Elapsed;
145	147
146	148		while ((ET.Elapsed - OldTime) < DelayInSeconds) do
147	149		begin
148	150		ET.SystemSleep(10);
149	151		end;
150	152
151	153		// DelayInSeconds has elapsed and now you can continue executing the code
152	154		```
153	155
154	156		See etdemo.pas for additional examples of component usage
155	157
156	158		#### EpikTimer as a profiler
157	159
158	160		EpikTimer can be used to profile the speed of procedures:
159	161
160	162		``` pascal
161	163		uses
162	164		{$ifdef PROFILING}epiktimer,{$endif}
163	165		...
164	166
165	167		type
166	168		TMyClass = class
167	169		private
168	170		{$ifdef PROFILING}
169	171		profiler: Tepiktimer;
170	172		{$endif}
171	173		...
172	174		end;
173	175
174	176		implementation
175	177
176	178		constructor TMyClass.Create(AOwner: TComponent);
177	179		begin
178	180		inherited Create(AOwner);
179	181
180	182		...
181	183
182	184		{$ifdef CARDROOM_PROFILING}
183	185		profiler := TEpikTimer.Create(Self)
184	186		{$endif}
185	187		end;
186	188
187	189		procedure TMyClass.MethodToBeProfiled;
188	190		begin
189	191		{$ifdef PROFILING}
190	192		profiler.Clear;
191	193		profiler.Start;
192	194		{$endif}
193	195		// do stuff
194	196		{$ifdef PROFILING}
195	197		OPDebugLn('TMyClass.MethodToBeProfiled ' + FloatToStr(profiler.Elapsed));
196	198		{$endif}
197	199		end;
198	200		```
199	201
200	202		### The ETDemo Application
201	203
202	204		The ETDemo application does not require EpikTimer to be installed in order to compile and operate. I never liked having to install a palette full of components only to find out that I didn't like any of them! :)
203	205
204	206		Installation
205	207
206	208		- Open etdemo.lpi
207	209		- compile
208	210		- run
209	211
210	212		### Console application
211	213
212	214		If you don't have an "Application" object instance as above, simply create the EpikTimer instance as follows. It must be manually freed when you are all done with it:
213	215
214		-	~~` ET := TEpikTimer.Create(nil)`\~~
215		-	~~` ... your code here ...`\~~
216		-	~~` ET.Free;`~~
	216	+	``` pascal
	217	+	ET := TEpikTimer.Create(nil)
	218	+	... your code here ...
	219	+	ET.Free;
	220	+	```
217	221
218	222		### See also
219	223
220	224		- [[doc:fcl/fptimer/index.html\|FPTimer included with FPC/Lazarus]]
221	225		- [[Yet another Running Timer]]
222	226
223	227		---
224	228		From the Free Pascal wiki, page "EpikTimer", as it stood on 2019-08-09 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
225	229		Category: Components

Back to history