Loading...
Searching...
No Matches
FilePoller::FilePoller Class Reference

File polling class. More...

## Public Member Functions

| constructor (string n_path, string n_mask, *hash< auto > n_opts)
| creates the object
| 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.
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
int | getPollCount ()
| returns the current poll count
bool | runOnce ()
| runs a single poll (useful for checking for errors inline before starting a background thread)
| setPath (string path)
| Changes the polling path.
abstract | singleFileEvent (hash< FilePollerFileEventInfo > event)
| called for each matching file individually when matching files are polled
int | start ()
| starts polling in the background; returns the thread ID of the polling thread
| startInline ()
| starts the polling operation inline (not in a background thread)
| stop ()
| stops the polling operation, returns when the polling operation has been stopped
| stopNoWait ()
| stops the polling operation, returns immediately
| waitStop ()
| Waits indefinitely for the polling operation to stop.

## Static Public Member Functions

static | checkPath (string path, string type, bool write=False)
| checks a path on the server file system

## 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 `"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

## 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 server file system

Exceptions

  DIR-ERROR | this exception is thrown if the server 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 regex_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 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 | ) |

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()
  - 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()