format, doc

Author: Mitchell Perilstein

Makefile

@@ -3,6 +3,9 @@
 #
 # Usage:  make [test|bench|clean]
 #
+# Copyright (C) 2014 Mitchell Perilstein
+# Licensed under GNU LGPL Version 3. See LICENSING file for details.
+#
 
 LIB   = libfast-mktime.so.1
 ALL   = $(LIB) benchmark unittest
@@ -20,7 +23,7 @@ test: $(ALL)
 	./unittest 
 	@echo
 	LD_PRELOAD=./$(LIB) ./unittest
-	
+
 bench:
 	@echo
 	@echo '## Benchmarking once with stock mktime and once with wrapper.'
@@ -29,6 +32,6 @@ bench:
 	./benchmark 3 1000000
 	@echo
 	LD_PRELOAD=./$(LIB) ./benchmark 3 1000000
-	
+
 clean:
 	@rm -f $(ALL)

README.md

@@ -1,18 +1,69 @@
 libfast-mktime
 ==============
 
-A C99 mktime(3) library interposer optimized for repeated calls in the same day.
+This is a micro-optimization for mktime(3) that will speed it up
+around 86x in the best case and have a slight impact in the worse.
+
+Motivation
+----------
+
+The system mktime(3) handles time zones, tzset(), leap years, input
+normalization, plus the obvious date calculations, all of which can
+take some cycles.  If your use case entails many mktime() calls within
+the same calendar day, there is an easy optimization which can show
+substantial savings.
+
+Algorithm
+---------
+
+The first call, call system mktime(), memoizing the date and the
+beginning of that date in epoch time. Then for subsequent calls, if
+they are on the same date, add the requested H:M:S to that saved
+midnight, skipping all the date calculations.  If the date is
+different, use the system mktime() again and memoize it.
+
+This package provides a libfast-mktime.so.1, defining only mktime()
+and intended to be interpose system mktime() as above, using
+LD_PRELOAD.
+
+Platforms
+---------
+
+So far, tested on i686 and x86_64 GNU/Linux.
 
 Building
 --------
 
     $ make
     $ make test
-    $ make bench				
+    $ make bench                                
 
 Usage
 -----
 
-    $ gcc your_prog.c
-    $ ./a.out			   		  ## regular
-    $ LD_PRELOAD=./libfast-mktime.so.1 ./a.out    ## faster?
+    $ LD_PRELOAD=./libfast-mktime.so.1 /path/to/your/program
+
+Benchmark
+---------
+
+    ## Benchmarking once with stock mktime and once with wrapper.
+    ## 3 trials of 1e6 sequential dates will be run.
+  
+    ./benchmark 3 1000000
+      0: 0.868179 s
+      1: 0.865169 s
+      2: 0.866598 s
+    avg: 0.866649 s
+    
+    LD_PRELOAD=./libfast-mktime.so.1 ./benchmark 3 1000000
+      0: 0.014434 s
+      1: 0.014622 s
+      2: 0.015013 s
+    avg: 0.014690 s
+
+License
+-------
+
+Copyright (C) 2014 Mitchell Perilstein. Licensed under GNU LGPL
+Version 3. See LICENSING file for details.
+

benchmark.c

@@ -1,3 +1,8 @@
+/*
+ * Copyright (C) 2014 Mitchell Perilstein
+ * Licensed under GNU LGPL Version 3. See LICENSING file for details.
+ */
+
 #include <time.h>
 #include <stdlib.h>
 #include <stdio.h>
@@ -15,14 +20,14 @@ struct tm * makeit(long ndates)
     struct tm * date_array = (struct tm *)malloc(ndates * sizeof(struct tm));
     if (!date_array)
     {
-	fprintf(stderr, "Too much malloc\n");
-	exit(1);
+        fprintf(stderr, "Too much malloc\n");
+        exit(1);
     }
 
     long s;
     for (s=0; s<ndates; s++)
     {
-        time_t t = s + 1;	// start at year 1
+        time_t t = s + 1;       // start at year 1
         gmtime_r(&t, &date_array[s]);
     }
 
@@ -37,24 +42,24 @@ float timeit(struct tm *dates, long ndates)
     long s;
     for (s=0; s<ndates; s++)
     {
-        time_t made = mktime(&dates[s]);      
+        time_t made = mktime(&dates[s]);
     }
 
     gettimeofday(&tend, NULL);
     return ((tend.tv_sec * 1e6 + tend.tv_usec)
-	- (tbeg.tv_sec * 1e6 + tbeg.tv_usec)) / 1e6;
+            - (tbeg.tv_sec * 1e6 + tbeg.tv_usec)) / 1e6;
 }
 
-int main(int argc, char **argv) 
+int main(int argc, char **argv)
 {
-    if (argc < 3) 
-	usage();
+    if (argc < 3)
+        usage();
 
     long trials = atol(argv[1]);
     long ndates = atol(argv[2]);
 
     if (ndates<1 || trials<1)
-	usage();
+        usage();
 
     struct tm *dates = makeit(ndates);
     float total      = 0.0;
@@ -63,7 +68,7 @@ int main(int argc, char **argv)
     for (i=0; i<trials; i++)
     {
         float secs = timeit(dates, ndates);
-	printf("%3d: %f s\n", (int)i, secs);
+        printf("%3d: %f s\n", (int)i, secs);
         total += secs;
     }
 

fast-mktime.c

@@ -1,3 +1,8 @@
+/*
+ * Copyright (C) 2014 Mitchell Perilstein
+ * Licensed under GNU LGPL Version 3. See LICENSING file for details.
+ */
+
 #include <time.h>
 #include <stdlib.h>
 #include <stdio.h>
@@ -16,27 +21,27 @@ time_t mktime(struct tm *tm)
     /* Load real mktime once into a static */
     if (!mktime_real)
     {
-	void *handle;
+        void *handle;
 
-	/* To forgive this cast, please see man dlopen(3). */
-	dlerror();
-	handle = dlsym(RTLD_NEXT, "mktime");
-	*(void **) (&mktime_real) = handle;
+        /* To forgive this cast, please see man dlopen(3). */
+        dlerror();
+        handle = dlsym(RTLD_NEXT, "mktime");
+        *(void **) (&mktime_real) = handle;
 
-	if (!mktime_real) 
+        if (!mktime_real)
         {
             fprintf(stderr, "loading mktime: %s\n", dlerror());
             exit(EXIT_FAILURE);
         }
     }
 
     /* the epoch time portion of the request */
-    hmsarg = 3600 * tm->tm_hour 
-	    +  60 * tm->tm_min 
+    hmsarg = 3600 * tm->tm_hour
+            +  60 * tm->tm_min
             +       tm->tm_sec;
 
-    if ( cache.tm_mday    == tm->tm_mday 
-         && cache.tm_mon  == tm->tm_mon 
+    if ( cache.tm_mday    == tm->tm_mday
+         && cache.tm_mon  == tm->tm_mon
          && cache.tm_year == tm->tm_year )
     {
         /* cached - just add h,m,s from request to midnight */

unittest.c

@@ -1,3 +1,8 @@
+/*
+ * Copyright (C) 2014 Mitchell Perilstein
+ * Licensed under GNU LGPL Version 3. See LICENSING file for details.
+ */
+
 #include <time.h>
 #include <stdlib.h>
 #include <stdio.h>
@@ -6,23 +11,23 @@
 #include <assert.h>
 
 void ok(int sec, int min, int hour, int day, int month, int year,
-	time_t expect, const char *title)
+        time_t expect, const char *title)
 {
     struct tm s;
-    s.tm_sec = sec;  
-    s.tm_min = min;  
+    s.tm_sec = sec;
+    s.tm_min = min;
     s.tm_hour = hour;
-    s.tm_mday = day; 
-    s.tm_mon = month;  
+    s.tm_mday = day;
+    s.tm_mon = month;
     s.tm_year = year;
     s.tm_isdst = 0;
 
     time_t result = mktime(&s);
 
-    printf("  %s: got %10d for %s\n", 
-	(result == expect ? "okay" : "fail"), 
-	result,
-	title);
+    printf("  %s: got %10lu for %s\n",
+           (result == expect ? "okay" : "fail"),
+           (unsigned long)result,
+           title);
 }
 
 int main()