Initial commit of Pollcat library

include/pollcat/pollcat.h

@@ -0,0 +1,133 @@
+/** Wrapper structure for poll()
+ *
+ *  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_POLLCAT_H_
+#define _INCLUDE_POLLCAT_POLLCAT_H_
+
+#ifndef POLLCAT_TIME_BASE
+#define POLLCAT_TIME_BASE 250
+#endif
+#ifndef POLLCAT_TIME_MINIMUM
+#define POLLCAT_TIME_MINIMUM 5
+#endif
+#ifndef POLLCAT_SIZE_INITIAL
+#define POLLCAT_SIZE_INITIAL 8
+#endif
+#ifndef POLLCAT_SIZE_INCREMENT
+#define POLLCAT_SIZE_INCREMENT 8
+#endif
+#ifndef POLLCAT_DEBUG
+#define POLLCAT_DEBUG 1
+#endif
+
+#include <stdlib.h>
+#include <poll.h>
+#if POLLCAT_DEBUG
+#include <stdio.h>
+#endif
+
+
+/** Optional function to call on fatal error; if unset an assert()-style message will be
+ *  printed on stderr and exit(1) called.
+ */
+typedef void (* pollcat_assert_f) (const char *file, int line, const char *mesg);
+extern pollcat_assert_f pollcat_assert_func;
+
+
+/** Base timeout for wrapped poll() calls in milliseconds; pollcat_time_reduce() may be
+ *  called to reduce this on a per-loop basis to improve latency of things like timers.
+ *  The default is POLLCAT_TIME_BASE.
+ */
+extern int pollcat_time_base;
+
+/** Minimum timeout for wrapped poll() calls in milliseconds; pollcat_time_reduce() will
+ *  not reduce the per-loop timeout below this value. The default is POLLCAT_TIME_MINIMUM.
+ */
+extern int pollcat_time_minimum;
+
+/** Initial size of the pollfd array. The default is POLLCAT_SIZE_INITIAL.
+ */
+extern size_t pollcat_size_initial;
+
+/** Incremental size of the pollfd array. The default is POLLCAT_SIZE_INCREMENT.
+ */
+extern size_t pollcat_size_increment;
+
+
+/** Add an FD to the poll array and set the events requested
+ *
+ *  \param  fd      File descriptor
+ *  \param  events  Bitmap of events from poll.h, such as POLLIN
+ */
+void pollcat_fd_add (int fd, short int events);
+
+/** Get request bits of an FD in the poll array
+ *
+ *  \param  fd  File descriptor
+ *
+ *  \return bitmap on success, <0 on error
+ */
+short int pollcat_events_get (int fd);
+
+/** Set request bits on an FD in the poll array
+ *
+ *  \param  fd      File descriptor
+ *  \param  events  Bitmap of events from poll.h, such as POLLIN
+ */
+void pollcat_events_set (int fd, short int events);
+
+/** Get result bits of an FD in the poll array
+ *
+ *  \param  fd  File descriptor
+ *
+ *  \return bitmap on success, 0 on error
+ */
+short int pollcat_revents (int fd);
+
+/** Remove an FD from the poll array
+ *
+ *  \param  fd  File descriptor
+ */
+void pollcat_fd_remove (int fd);
+
+
+/** Reduce the current timeout
+ *
+ *  \param  time  New timeout in milliseconds
+ */
+void pollcat_time_reduce (int time);
+
+
+/** Wraps the system poll() command using the internal pollfd array and timeout
+ *
+ *  \return as per poll(), <0 on error
+ */
+int pollcat_poll (void);
+
+
+#if POLLCAT_DEBUG
+/** Prints the pollfd array to a given file handle
+ */
+void pollcat_dump (FILE *fp);
+#endif
+
+
+#endif /* _INCLUDE_POLLCAT_POLLCAT_H_ */