VFS_cron will emit diffs to subscribers based on wall-clock time. More...

#include <VFS_cron.h>

Inheritance diagram for VFS_cron:

Classes
class	crontime
	A class to represent a crontime, which can be matched against a (current) time to see if it is active. More...

Public Member Functions
Q_INVOKABLE	VFS_cron (QString crontab)

virtual	~VFS_cron ()

virtual VFS_node *	find (VFS_request *r)

virtual bool	isContainer ()
	A VFS_cron node cannot contain children, however listing the contents will return the entry list. More...

virtual QString	reportDetails ()

Public Member Functions inherited from VFS_node
Q_INVOKABLE	VFS_node ()
	The VFS_node constructor will add its instance to the VFS_node::__allNodes global node registry, observing thread safety rules. More...

virtual	~VFS_node ()
	VFS_node destructor. More...

virtual VFS_node *	append (QString name, VFS_node *node, bool containerCheck=true, QString user="server")
	Append a VFS_node as a child of this node. More...

QString	className ()
	Return the class name of a node. More...

virtual VFS_request *	createRequest (VFS_request::requestType type, QString path, QString user="unknown", QJsonDocument data=QJsonDocument(), QJsonObject metadata=QJsonObject(), bool dontDelete=false)
	Create a new VFS_request with this object as _origin. More...

VFS_node *	find (QString path)
	Find a node by string path. More...

VFS_node *	findChildWithName (QString name)
	Check if a child with a given name exists. More...

virtual VFS_node *	mount ()
	Mount this node. More...

QString	uniqueChildName (QString name)
	Generate a unique child name. More...

virtual VFS_node *	unmount ()
	Unmount this node. More...

virtual bool	validChildName (QString name)
	Check if a node name is valid. More...

Protected Slots
virtual void	initialize ()
	Schedule a start for the scheduler. More...

virtual void	startCron ()
	Start the scheduler. More...

Protected Member Functions
virtual QByteArray	icon ()
	Return the clock icon from VFS_icons. More...

virtual void	ls (VFS_request *r)
	List all entries in the crontab by name. More...

virtual void	read (VFS_request *r)
	Read or list the event entries. More...

virtual void	subscribe (VFS_request *r)

virtual void	timerEvent (QTimerEvent *event)
	Scan the event map for entries that match the current time. More...

virtual void	unsubscribe (VFS_request *r)

Protected Member Functions inherited from VFS_node
virtual void	aclDefaults (VFS_request *r)
	Return default values and features associated wth this node. More...

void	addACLDefault (QJsonObject &acl, bool value, QString description="")
	Add a default value to the acl object. More...

void	addACLFeature (QJsonObject &acl, QString feature, bool value, QString description="")
	Add a feature to the acl object. More...

void	addACLFeatureGroup (QJsonObject &acl, QString feature, QString group, bool value)
	Add a feature group to the acl object. More...

void	addACLFeatureUser (QJsonObject &acl, QString feature, QString user, bool value)
	Add a feature user to the acl object. More...

void	addACLGroup (QJsonObject &acl, QString group, bool value)
	Add a group to the acl object. More...

void	addACLUser (QJsonObject &acl, QString user, bool value)
	Add a user to the acl object. More...

virtual void	issueRequest (VFS_node target, VFS_request t)
	Issue a VFS_request to its target. More...

virtual void	issueRequest (VFS_request *t)
	A convenience function. More...

virtual void	issueResponse (VFS_request *t)
	Once a request has been completed, issue a response. More...

virtual void	metadata (VFS_request *r)
	Fetch the metadata of this node. More...

virtual void	releaseLock (VFS_request *r)
	Release a lock on this node. More...

virtual void	report (VFS_request *r)
	Report debugging information about the current state of this node. More...

virtual void	requestLock (VFS_request *r)
	Request a lock on this node. More...

virtual void	rm (VFS_request *r)
	Remove a child entry from a node, or the node itself. More...

virtual void	submit (VFS_request *r)
	Submit a diff to a node. More...

virtual void	unsubscribePath (QString path)
	Unsubscribe all references to a subpath. More...

virtual void	write (VFS_request *r)
	Write data to this node. More...

Protected Attributes
int	_cronID
	the timerID of the cron node More...

QMultiMap< QString, crontime >	_crontab
	map of "event:crontime" fields More...

Protected Attributes inherited from VFS_node
VFS_children	_children
	This node's children. More...

QMutex	_lock
	A recursive mutex that is local to this node. More...

VFS_subscriptionType	_subscribers
	This node's subscribers. These subscribers will receive diff notifications. More...

Private Member Functions
virtual void	parseCrontab (QString tab)

Additional Inherited Members
Public Slots inherited from VFS_node
virtual void	applyDiff (VFS_request *r)
	Apply a diff received via subscription. More...

virtual void	executeRequest (VFS_request *t)
	Based on the VFS_request::requestType, execute the function associated with an operation. More...

void	notifySubscribers (VFS_node origin, VFS_request t)
	Propagate a diff to subscribers. More...

virtual void	receiveResponse (VFS_request *t)
	Once a VFS_request has been completed, a response will be issued back to its _origin. More...

void	remove (bool andDelete)
	Remove a child node. More...

virtual void	remove (VFS_node node=nullptr, QString name=nullptr, QString user="server")
	Remove a child node from this node. More...

virtual void	subtreeRequest (VFS_request *t)
	find() the target of a VFS_request, and execute the request More...

virtual void	unsubscribeAll (VFS_node *n)
	Remove all references to a subscriber from this node. More...

Signals inherited from VFS_node
void	diff (VFS_node origin, VFS_request t)
	Emit a diff, which will trigger notifySubscribers() for a mounted node. More...

void	finished (bool andDelete=false)
	Emitted if a thread fails to create its node, or a node is rm()'d, or any other reason a node has completed its lifecycle. It is deleted if `andDelete==true`. More...

void	mounted ()
	Emitted when a node is mount()ed. More...

void	unmounted (VFS_node *self)
	Emitted when a node is unmount()ed. More...

Static Public Member Functions inherited from VFS_node
static bool	__isNode (VFS_node *)
	Check to see if a node is in the global registry. More...

static QString	code (QString nodename, QString libname, QString &error)
	Fetch code or any other resource from a node. More...

Detailed Description

VFS_cron will emit diffs to subscribers based on wall-clock time.

Todo:: incorporate UTC offset which doesn't currently exist, despite documentation

the crontab format is a '|'-delimited list of events and crontimes which is similar to unix crontab.

Crontime entry format:

* * * * * * * O
| | | | | | | |
| | | | | | | +-- UTC Offset        (range: -12 to +13, or 0 if missing.  Sign is required)
| | | | | | +---- Year              (range: quint16)
| | | | | +------ Day of the Week   (range: 0-7, 0 for Sunday)
| | | | +-------- Month of the Year (range: 1-12)
| | | +---------- Day of the Month  (range: 1-31)
| | +------------ Hour              (range: 0-23)
| +-------------- Minute            (range: 0-59)
+---------------- Second            (range: 0-59)

Attention: If a timezone offset is not provided for a crontime entry, UTC+0 will be assumed.

Unlike unix cron non-numeric values are not accepted. However, lists and ranges can be used, separated by commas.

For example:

Entry	Effect
start: *	every second of every day
disco: 0 15 * *	at :15 of wall-clock time every hour of every day
weekend: 0 0 0 * * 6,0 *	at midnight server time on saturday and sunday
lunch: 0 30 12 * * 1-5 * -5	lunch in NY at 12:30pm on weekdays
sometime: 2-35,47 * 1	certain seconds during the 1 o'clock hour, server time
doomsday: * * * * * * 2048,1912	during these unfortunate years, every second will have an event

A crontab XML config parameter may be:

Entry	Effect
start: 4 \| bling: * 10	"start" when second=4 any time, "bling" every second when minute=10
midnight_NY: 0 0 0 * * * * -5 \| midnight_LA: 0 0 0 * * * * -8	"midnight_NY" when it's midnight at UTC-5 in NY, "midnight_LA" when it's midnight at UTC-8 in LA
rarely: 0 12 14,16 4 * 2 * -7	"rarely" when it's 2:12:00pm or 4:12:00pm on the 4th of every month that is a Tuesday, in Colorado. This only happens once or twice a year.

Admittedly, not all time patterns can be represented with a single crontab string, but combinations of them can certainly represent any time pattern.

Todo:: multiple crontime entries with the same name, methods and testing

To create a yearly scheduled birthday event in an xml config file:

<vfs>
        <!-- Michael's birthday moment, at noon in Japan -->
        <cron name='cron' crontab='birthday: 0 0 12 23 2 * * +9' />
</vfs>

To create a yearly scheduled birthday event in C++:

void somenode::scheduleBirthday()
{
        //schedule a birthday event
 
        QString _scheduler = "/services/cron";
        QJsonObject o;
        o["birthday"] = "0 30 3 4 1 * * +1";    //Chris' birthday moment, at noon in Paris
 
        VFS_request *r = createRequest(VFS_request::subscribe, _scheduler+"/birthday", className(), QJsonDocument(o) );
        r->_metadata["createIfMissing"] = true;
        issueRequest(r);
}

Then, when the event fires:

void somenode::applyDiff(VFS_request *r)
{
        if (r->_path == "birthday")
        {
                VFS::WARN("You are now a year older.");
        }
 
        //note that since we are not emitting a diff in this subclass implementation, we need to call the base class.
        VFS_node::applyDiff(r);
}

You will almost certainly want to put this node in its own thread, as it must check all cron entries every second for matches.

Events are subpaths of the cron node, and can be deleted or created as named paths with write() and rm().

Definition at line 8 of file VFS_cron.h.

Constructor & Destructor Documentation

◆ VFS_cron()

VFS_cron::VFS_cron ( QString crontab )

explicit

Parameters

crontab A '|'-delimited string of crontab entries.

A VFS_cron node can be initialized with a crontab, provided by the config xml file. This is not a requirement, though, as paths can be later created by writing crontimes to paths on the node.

Definition at line 115 of file VFS_cron.cpp.

◆ ~VFS_cron()

VFS_cron::~VFS_cron ( )

virtual

Definition at line 126 of file VFS_cron.cpp.

Member Function Documentation

◆ find()

VFS_node * VFS_cron::find ( VFS_request * r )

virtual

Parameters

r	The VFS_request performing a search

Returns: VFS_node*

The find function will return this node if the request path is empty, createIfMissing is true in the request metadata, or if an event with the request _path matches a known entry.

Reimplemented from VFS_node.

Definition at line 138 of file VFS_cron.cpp.

◆ icon()

QByteArray VFS_cron::icon ( )

protectedvirtual

Return the clock icon from VFS_icons.

Returns: The clock icon

Reimplemented from VFS_node.

Definition at line 194 of file VFS_cron.cpp.

◆ initialize

void VFS_cron::initialize ( )

protectedvirtualslot

Schedule a start for the scheduler.

Initialize the node, which is to schedule a startCron in the future near the beginning of the next second.

This should be accurate within a millisecond.

Definition at line 207 of file VFS_cron.cpp.

◆ isContainer()

bool VFS_cron::isContainer ( )

virtual

A VFS_cron node cannot contain children, however listing the contents will return the entry list.

Returns: true

Reimplemented from VFS_node.

Definition at line 184 of file VFS_cron.cpp.

◆ ls()

void VFS_cron::ls ( VFS_request * r )

protectedvirtual

List all entries in the crontab by name.

Parameters

r	The VFS_request object

This will provide essentially a directory listing of the current events. Those events can be read as a path.

Reimplemented from VFS_node.

Definition at line 373 of file VFS_cron.cpp.

◆ parseCrontab()

void VFS_cron::parseCrontab ( QString tab )

privatevirtual

Parameters

tab	The crontab

Definition at line 300 of file VFS_cron.cpp.

◆ read()

void VFS_cron::read ( VFS_request * r )

protectedvirtual

Read or list the event entries.

Parameters

r	The VFS_request object

If r->_path == "", list the entries.

If r->_path is a known entry, r->_data["crontime"] will be returned as a crontime string.

An unknown path entry will cause read to fail.

Reimplemented from VFS_node.

Definition at line 389 of file VFS_cron.cpp.

◆ reportDetails()

QString VFS_cron::reportDetails ( )

virtual

Returns: QString

Will report the current scheduled events and their crontime values. Useful in the VFS_httpd_browser for learning what the node has currently scheduled.

See also: VFS_httpd_browser

Reimplemented from VFS_node.

Definition at line 162 of file VFS_cron.cpp.

◆ startCron

void VFS_cron::startCron ( )

protectedvirtualslot

Start the scheduler.

This function will block for a few milliseconds to get as close as possible to the start of the next second. Ideally events are scanned at the beginning of each wallclock second. It will fire an event once per second.

Definition at line 228 of file VFS_cron.cpp.

◆ subscribe()

void VFS_cron::subscribe ( VFS_request * r )

protectedvirtual

Parameters

r	The VFS_request containing subscription details

Create a subscription.

If r->_metadata["createIfMissing"] == true, an event entry will be parsed from all crontime-formatted entries in the r->_data object.

Reimplemented from VFS_node.

Definition at line 330 of file VFS_cron.cpp.

◆ timerEvent()

void VFS_cron::timerEvent ( QTimerEvent * event )

protectedvirtual

Scan the event map for entries that match the current time.

Parameters

event The QObject's timer event

If the event map contains a matching entry, create a VFS_request::diff and issue it to subscribers. The issued request will contain the current time, and the path will be the event name.

Definition at line 248 of file VFS_cron.cpp.

◆ unsubscribe()

void VFS_cron::unsubscribe ( VFS_request * r )

protectedvirtual

Parameters

r	The VFS_request object

Remove the subscription entry in r->_path.

Note that even when the last subscriber has unsubscribed, the event will still exist in the crontab.

Reimplemented from VFS_node.

Definition at line 435 of file VFS_cron.cpp.

Member Data Documentation

◆ _cronID

int VFS_cron::_cronID

protected

the timerID of the cron node

Definition at line 53 of file VFS_cron.h.

◆ _crontab

QMultiMap<QString, crontime> VFS_cron::_crontab

protected

map of "event:crontime" fields

Definition at line 52 of file VFS_cron.h.

The documentation for this class was generated from the following files:

Classes

Public Member Functions

Protected Slots

Protected Member Functions

Protected Attributes

Private Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ VFS_cron()

◆ ~VFS_cron()

Member Function Documentation

◆ find()

◆ icon()

◆ initialize

◆ isContainer()

◆ ls()

◆ parseCrontab()

◆ read()

◆ reportDetails()

◆ startCron

◆ subscribe()

◆ timerEvent()

◆ unsubscribe()

Member Data Documentation

◆ _cronID

◆ _crontab