File polling class. More...

#include <FilePoller.qm.dox.h>

Public Member Methods
	constructor (string n_path, string n_mask, *hash< auto > n_opts)
	creates the object More...

	destructor ()
	stops the polling operation if in progress and destroys the object

	fileEvent (list< hash< FilePollerFileEventInfo > > files)
	Called for each poll event with a list of all files matched. More...

list< hash< FilePollerFileEventInfo > >	getFiles (int sort=FilePoller::SortNone, int order=FilePoller::OrderAsc)
	returns a list of regular file hashes matching any file name mask set for the object More...

int	getPollCount ()
	returns the current poll count

bool	runOnce ()
	runs a single poll (useful for checking for errors inline before starting a background thread)

abstract	singleFileEvent (hash< FilePollerFileEventInfo > event)
	called for each matching file individually when matching files are polled More...

int	start ()
	starts polling in the background; returns the thread ID of the polling thread More...

	startInline ()
	starts the polling operation inline (not in a background thread) More...

	stop ()
	stops the polling operation, returns when the polling operation has been stopped More...

	stopNoWait ()
	stops the polling operation, returns immediately More...

	waitStop ()
	Waits indefinitely for the polling operation to stop. More...

Static Public Member Methods
static	checkPath (string path, string type, bool write=False)
	checks a path on the local file system More...

Public Attributes
const	Options = ...
	known constructor() options

const	OrderAsc = 0
	ascending sort order

const	OrderDesc = 1
	descending sort order

const	RequiredKeys = ...
	minimum required keys for all constructors

const	SortDate = 2
	sort by date

const	SortName = 1
	sort by name

const	SortNone = 0
	no sorting

Private Member Methods
	fileSleep (softint secs)
	sleeps for the specificed number of seconds

	logDebug (string fmt)
	calls `"log_debug"` with verbose debugging information; if set

	logDetail (string fmt)
	calls `"log_detail"` with detail information; if set

	logInfo (string fmt)
	calls `"log_info"` with important information, if set

Qore::Thread::Mutex	m ()
	start mutex

	run ()
	starts the polling operation

Qore::Thread::Counter	sc ()
	stop counter

Private Attributes
bool	fatal = False
	internal fatal error flag

*code	log_debug
	optional debug log closure

*code	log_detail
	optional detail log closure

*code	log_info
	optional info log closure

string	mask
	file name mask

*softint	minage
	minimum file age in seconds before the file will be included in the list returned

string	path
	path to monitor

int	poll_interval = 10
	poll interval in seconds

int	pollcnt = 0
	internal poll counter

int	reopt
	regex options

bool	runflag = False
	run flag

*code	sleep
	optional sleep closure

int	sort_order = OrderAsc
	file sort order

int	sort_type = SortName
	file sort type

*code	start_thread
	optional start thread closure

int	tid
	polling tid

Detailed Description

File polling class.

Member Function Documentation

◆ checkPath()

static FilePoller::FilePoller::checkPath	(	string	path,
		string	type,
		bool	write = `False`
	)

static

checks a path on the local file system

Exceptions

DIR-ERROR this exception is thrown if the local path does not exist, is not readable, is not a directory, or should be writable and is not

◆ constructor()

FilePoller::FilePoller::constructor	(	string	n_path,
		string	n_mask,
		*hash< auto >	n_opts
	)

creates the object

Parameters

n_path	the path to poll
n_mask	the regular expression mask to use to match the files
n_opts	a hash with the following optional keys: `"log_info"`: a closure or call reference taking a single string argument as an information message for logging `"log_detail"`: a closure or call reference taking a single string argument as a detail information message for logging `"log_debug"`: a closure or call reference taking a single string argument as a debug information message for logging `"minage"`: the minimum file age in seconds as calculated from the file's "last modified" timestamp (`mtime` attribute) before a file will be acquired (default: 0); use this option if files could be otherwise read while being written `"poll_interval"`: an integer poll interval in seconds; if this option is not supplied, then the default `poll_inteval` is 10 seconds `"reopt"`: regular expression options; see Regular Expression Constants for possible values (ex Qore::RE_Caseless for case-insensitive matches) `"sleep"`: (required when imported into a context where Qore::PO_NO_PROCESS_CONTROL is set) a closure or call reference to use instead of Qore::sleep() (if not set then Qore::sleep() will be used) `"sort_order"`: an integer constant giving the sort order; valid options are: OrderAsc: ascending (the default) OrderDesc: descending `"sort_type"`: an integer constant giving the sort type; valid options are: SortNone: no sort SortName: sort by file name (the default) SortDate: sort by the file's last modified date `"start_thread"`: (required when imported into a context where Qore::PO_NO_THREAD_CONTROL is set) a closure or call reference for starting threads; must return the integer thread ID (if not set then Background Operator (background) will be used)

Exceptions

FILEPOLLER-CONSTRUCTOR-ERROR invalid option

◆ fileEvent()

FilePoller::FilePoller::fileEvent ( list< hash< FilePollerFileEventInfo > > files )

Called for each poll event with a list of all files matched.

Calls singleFileEvent() on each file hash in the list

◆ getFiles()

list< hash< FilePollerFileEventInfo > > FilePoller::FilePoller::getFiles	(	int	sort = `FilePoller::SortNone`,
		int	order = `FilePoller::OrderAsc`
	)

returns a list of regular file hashes matching any file name mask set for the object

Parameters

sort	the sort option for the list returned
order	the ordering of sorted data returned

Returns: a list of FilePollerFileEventInfo hashes for each matched file

◆ singleFileEvent()

abstract FilePoller::FilePoller::singleFileEvent ( hash< FilePollerFileEventInfo > event )

pure virtual

called for each matching file individually when matching files are polled

If any error occurs here, the error is logged and the polling operation is retried

Parameters

event

a hash of file data and information with the following keys:

name: the name of the file, link, or directory
filepath: the complete path to the file including the directory
size: the size of the file in bytes
uid: the UID of the owner of the file
gid: the GID of the owner of the file
mode: the permissions / mode of the file
atime: the last accessed date/time of the file
mtime: the last modified date/time of the file
type: the type of file; one of:
- "REGULAR"
- "DIRECTORY"
- "SYMBOLIC-LINK"
- "BLOCK-DEVICE"
- "CHARACTER-DEVICE"
- "FIFO"
- "SYMBOLIC-LINK"
- "SOCKET"
- "UNKNOWN"
perm: a string giving UNIX-style permissions for the file (ex: "-rwxr-xr-x")

◆ start()

int FilePoller::FilePoller::start ( )

starts polling in the background; returns the thread ID of the polling thread

if polling had already been started, then the thread ID of the polling thread is returned immediately

◆ startInline()

FilePoller::FilePoller::startInline ( )

starts the polling operation inline (not in a background thread)

Exceptions

FILEPOLLER-ERROR this exception is thrown if polling is already in progress

◆ stop()

FilePoller::FilePoller::stop ( )

stops the polling operation, returns when the polling operation has been stopped

if polling was not in progress then this method returns immediately

Exceptions

THREAD-ERROR this exception is thrown if this method is called from the polling thread since it would result in a deadlock

See also

◆ stopNoWait()

FilePoller::FilePoller::stopNoWait ( )

stops the polling operation, returns immediately

See also

◆ waitStop()

FilePoller::FilePoller::waitStop ( )

Waits indefinitely for the polling operation to stop.

If polling was not in progress then this method returns immediately

Exceptions

THREAD-ERROR this exception is thrown if this method is called from the event thread since it would result in a deadlock

See also

Public Member Methods

Static Public Member Methods

Public Attributes

Private Member Methods

Private Attributes

Detailed Description

Member Function Documentation

◆ checkPath()

◆ constructor()

◆ fileEvent()

◆ getFiles()

◆ singleFileEvent()

◆ start()

◆ startInline()

◆ stop()

◆ stopNoWait()

◆ waitStop()