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


/** This was removed and replaced with a simpler implementation which allowed slow/late
 *  timers to run reliably.  Setting it now has no effect. */
extern pollcat_time_t  pollcat_timer_dispatch_thresh __attribute__((deprecated));


/** 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_ */