FilePoller::FilePoller Class Referenceabstract

file polling class More...

## Public Member Functions

| constructor (string n_path, string n_mask, *hash n_opts)
| creates the object More...
| destructor ()
| stops the polling operation if in progress and destroys the object
| fileEvent (list files)
| called for each poll event with a list of all files matched; calls singleFileEvent() on each file hash in the list
list | 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 fih)
| called for each matching file individually whenever matching files are polled with the list of matching file names; if any error occurs here, the error is logged and the polling operation is retried 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; if polling was not in progress then this method returns immediately More...

## Static Public Member Functions

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

## Protected Member Functions

| fileSleep (softint secs)
| sleeps for the specificed number of seconds
| logDebug (string fmt)
| calls the `"log_debug"` closure or call reference with verbose debugging information
| logDetail (string fmt)
| calls the `"log_detail"` closure or call reference with detail information
| logInfo (string fmt)
| calls the `"log_info"` closure or call reference with important information
Qore::Thread::Mutex | m ()
| start mutex
| run ()
| starts the polling operation
Qore::Thread::Counter | sc ()
| stop counter

## Protected 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 | 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

## getFiles()

list 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 regular file hashes with the following keys in each list element:
  - `name:` the name of the file, link, or directory
  - `filepath:` the complete file path
  - `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 is always `"REGULAR"`
  - `perm:` a string giving UNIX-style permissions for the file (ex: "-rwxr-xr-x")

## singleFileEvent()

abstract FilePoller::FilePoller::singleFileEvent | ( | hash | fih | ) |

pure virtual

called for each matching file individually whenever matching files are polled with the list of matching file names; if any error occurs here, the error is logged and the polling operation is retried

Parameters

  fih

  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"`, or `"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()
  - waitStop()

## stopNoWait()

FilePoller::FilePoller::stopNoWait | ( |  | ) |

stops the polling operation, returns immediately

See also
  - stop()
  - waitStop()

## 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
  - stop()
  - stopNoWait()