Initial commit of Pollcat library

include/pollcat/timer.h

@@ -0,0 +1,95 @@
+/** Millisecond-resolution event timers
+ *
+ *  This file is part of the Pollcat Library.
+ *  Copyright (C) 2022 Expatria Technologies Inc.
+ *  Contact: Morgan Hughes <morgan@expatria.ca>
+ *
+ *  The Pollcat Library is free software: you can redistribute it and/or modify it under
+ *  the terms of the the GNU Lesser General Public License as published by the Free
+ *  Software Foundation; either version 3 of the License, 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 copies of the GNU General Public License and the GNU Lesser
+ *  General Public License along with the Pollcat Library.  If not, see
+ *  https://www.gnu.org/licenses/
+ *
+ *  vim:ts=4:noexpandtab
+ */
+#ifndef _INCLUDE_POLLCAT_TIMER_H_
+#define _INCLUDE_POLLCAT_TIMER_H_
+#include <stdint.h>
+
+
+/** Clocks type adjustable in size, units milliseconds for compatibility with poll() */
+typedef uint64_t pollcat_time_t;
+
+
+/** Grace period in milliseconds for late timers, set to 0 for exact match */
+extern pollcat_time_t  pollcat_timer_dispatch_thresh;
+
+
+/** Maximum number of times to run the dispatch loop, set to -1 for no limit */
+extern int pollcat_timer_dispatch_max;
+
+
+/** Timer callbacks type takes a single void pointer */
+typedef void (* pollcat_timer_f)(void *);
+
+
+/** Timer struct; zero-fill to init */
+struct pollcat_timer
+{
+	pollcat_timer_f  func;
+	pollcat_time_t   due;
+	void            *arg;
+
+	struct pollcat_timer *next;
+	struct pollcat_timer *prev;
+};
+
+
+/** Detach a timer from the active list
+ *
+ *  \param  timer  Pointer to timer struct
+ */
+void pollcat_timer_detach (struct pollcat_timer *timer);
+
+/** Attach or re-attach a timer to the active list
+ *
+ *  \param  timer   Pointer to timer struct
+ *  \param  msec    Delay in milliseconds
+ *  \param  func    Callback function
+ *  \param  arg     Argument to callback function
+ */
+void pollcat_timer_attach (struct pollcat_timer *timer,
+                           pollcat_time_t        msec,
+                           pollcat_timer_f       func,
+                           void                 *arg);
+
+/** Returns nonzero if timer is attached
+ *
+ *  \param  timer   Pointer to timer struct
+ *
+ *  \return  >0 if timer is attached
+ */
+int pollcat_timer_is_attached (struct pollcat_timer *timer);
+
+
+/** Reduce the poll() timeout
+ *
+ *  This should be called each main loop before the pollcat_poll() call, so that a ready
+ *  timer isn't delayed.
+ */
+void pollcat_timer_reduce_timeout (void);
+
+
+/** Dispatch ready timers
+ */
+void pollcat_timer_dispatch (void);
+
+
+#endif /* _INCLUDE_POLLCAT_TIMER_H_ */