teensy-core-4.1/teensy3/EventResponder.h

/* EventResponder - Simple event-based programming for Arduino
 * Copyright 2017 Paul Stoffregen
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

/* EventResponder is an experimental API, almost certain to
 * incompatibly change as it develops.  Please understand any
 * programs you write now using EventResponder may need to be
 * updated as EventResponder develops.
 *
 * Please post EventResponder post your feedback here:
 *     https://forum.pjrc.com/threads/44723-Arduino-Events
 */

#if !defined(EventResponder_h) && defined(__cplusplus)
#define EventResponder_h

#include <Arduino.h>

/* EventResponder lets you control how your program responds to an event.
 * Imagine a basketball or football (American soccer) player who gets the
 * ball.  Usually they will pass to another player who has the best
 * opportunity to score.  Similarly in Arduino programming, events are
 * often triggered within interrupts or other timing sensitive code.
 * EventResponder can call your function a short time later, giving you
 * the ability to use Arduino functions and libraries which would not
 * be safe to use from an interrupt.  However, some situations do call
 * for the most immediate response, even if doing so is more difficult.
 * EventResponder lets you choose how your function will be called,
 * without editing the timers or libraries which trigger the events.
 */

class EventResponder;
typedef EventResponder& EventResponderRef;
typedef void (*EventResponderFunction)(EventResponderRef);
class EventResponder
{
public:
	constexpr EventResponder() {
	}
	~EventResponder() {
		detach();
	}
	enum EventType { // these are not meant for public consumption...
		EventTypeDetached = 0, // no function is called
		EventTypeYield,        // function is called from yield()
		EventTypeImmediate,    // function is called immediately
		EventTypeInterrupt,    // function is called from interrupt
		EventTypeThread        // function is run as a new thread
	};

	// Attach a function to be called from yield().  This should be the
	// default way to use EventResponder.  Calls from yield() allow use
	// of Arduino libraries, String, Serial, etc.
	void attach(EventResponderFunction function) {
		detach();
		_function = function;
		_type = EventTypeYield;
	}

	// Attach a function to be called immediately.  This provides the
	// fastest possible response, but your function must be carefully
	// designed.
	void attachImmediate(EventResponderFunction function) {
		detach();
		_function = function;
		_type = EventTypeImmediate;
	}

	// Attach a function to be called from a low priority interrupt.
	// Boards not supporting software triggered interrupts will implement
	// this as attachImmediate.  On ARM and other platforms with software
	// interrupts, this allow fast interrupt-based response, but with less
	// disruption to other libraries requiring their own interrupts.
	void attachInterrupt(EventResponderFunction function) {
		detach();
		_function = function;
		_type = EventTypeInterrupt;
		// TODO: configure PendSV
	}

	// Attach a function to be called as its own thread.  Boards not running
	// a RTOS or pre-emptive scheduler shall implement this as attach().
	void attachThread(EventResponderFunction function, void *param=nullptr) {
		attach(function); // for non-RTOS usage, compile as default attach
	}

	// Do not call any function.  The user's program must occasionally check
	// whether the event has occurred, or use one of the wait functions.
	void detach();

	// Trigger the event.  An optional status code and data may be provided.
	// The code triggering the event does NOT control which of the above
	// response methods will be used.
	virtual void triggerEvent(int status=0, void *data=nullptr) {
		_status = status;
		_data = data;
		if (_type == EventTypeImmediate) {
			(*_function)(*this);
		} else {
			triggerEventNotImmediate();
		}
	}
	// Clear an event which has been triggered, but has not yet caused a
	// function to be called.
	bool clearEvent();

	// Get the event's status code.  Typically this will indicate if the event was
	// triggered due to successful completion, or how much data was successfully
	// processed (positive numbers) or an error (negative numbers).  The
	// exact meaning of this status code depends on the code or library which
	// triggers the event.
	int getStatus() { return _status; }

	// Get the optional data pointer associated with the event.  Often this
	// will be NULL, or will be the object instance which triggered the event.
	// Some libraries may use this to pass data associated with the event.
	void * getData() { return _data; }

	// An optional "context" may be associated with each EventResponder.
	// When more than one EventResponder has the same function attached, these
	// may be used to allow the function to obtain extra information needed
	// depending on which EventResponder called it.
	void setContext(void *context) { _context = context; }
	void * getContext() { return _context; }

	// Wait for event(s) to occur.  These are most likely to be useful when
	// used with a scheduler or RTOS.
	bool waitForEvent(EventResponderRef event, int timeout);
	EventResponder * waitForEvent(EventResponder *list, int listsize, int timeout);

	static void runFromYield() {
		EventResponder *first = firstYield;
		if (first && !runningFromYield) {
			runningFromYield = true;
			firstYield = first->_next;
			if (firstYield) firstYield->_prev = nullptr;
			first->_pending = false;
			(*(first->_function))(*first);
			runningFromYield = false;
		}
	}
	static void runFromInterrupt();
	operator bool() { return _pending; }
protected:
	void triggerEventNotImmediate();
	int _status = 0;
	EventResponderFunction _function = nullptr;
	void *_data = nullptr;
	void *_context = nullptr;
	EventResponder *_next = nullptr;
	EventResponder *_prev = nullptr;
	EventType _type = EventTypeDetached;
	bool _pending = false;
	static EventResponder *firstYield;
	static EventResponder *lastYield;
	static EventResponder *firstInterrupt;
	static EventResponder *lastInterrupt;
	static bool runningFromYield;
};

class MillisTimer
{
public:
	constexpr MillisTimer() {
	}
	~MillisTimer() {
		end();
	}
	void begin(unsigned long milliseconds, EventResponderRef event);
	void beginRepeat(unsigned long milliseconds, EventResponderRef event);
	void end();
	static void runFromTimer();
private:
	void addToList();
	unsigned long _ms = 0;
	unsigned long _reload = 0;
	MillisTimer *_next = nullptr;
	MillisTimer *_prev = nullptr;
	EventResponder *_event = nullptr;
	bool isQueued = false;
	static MillisTimer *list;
};

#endif