/** Wrapper structure for poll()
 *
 *  This file is part of the Pollcat Library.
 *  Copyright (C) 2022,2025 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>
#include <stdio.h>


/** 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);


/** Prints the pollfd array to a given file handle, if POLLCAT_DEBUG is nonzero
 */
void pollcat_dump (FILE *fp);


#endif /* _INCLUDE_POLLCAT_POLLCAT_H_ */