libfswatch  1.9.3
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
fsw::monitor Class Referenceabstract

Base class of all monitors. More...

#include <monitor.hpp>

Inheritance diagram for fsw::monitor:
fsw::fen_monitor fsw::fsevents_monitor fsw::inotify_monitor fsw::kqueue_monitor fsw::poll_monitor fsw::windows_monitor

Public Member Functions

 monitor (std::vector< std::string > paths, FSW_EVENT_CALLBACK *callback, void *context=nullptr)
 Constructs a monitor watching the specified paths. More...
 
virtual ~monitor ()
 Destructs a monitor instance. More...
 
 monitor (const monitor &orig)=delete
 This class is not copy constructible.
 
monitoroperator= (const monitor &that)=delete
 This class is not copy assignable.
 
void set_property (const std::string &name, const std::string &value)
 Sets a custom property. More...
 
void set_properties (const std::map< std::string, std::string > options)
 Sets the custom properties. More...
 
std::string get_property (std::string name)
 Gets the value of a property. More...
 
void set_latency (double latency)
 Sets the latency. More...
 
void set_fire_idle_event (bool fire_idle_event)
 Sets the fire idle event flag. More...
 
void set_allow_overflow (bool overflow)
 Notify buffer overflows as change events. More...
 
void set_recursive (bool recursive)
 Recursively scan subdirectories. More...
 
void set_directory_only (bool directory_only)
 Watch directories only. More...
 
void add_filter (const monitor_filter &filter)
 Add a path filter. More...
 
void set_filters (const std::vector< monitor_filter > &filters)
 Set the path filters. More...
 
void set_follow_symlinks (bool follow)
 Follow symlinks. More...
 
void * get_context () const
 Get the pointer to the context data. More...
 
void set_context (void *context)
 Set the context data. More...
 
void start ()
 Start the monitor. More...
 
void stop ()
 Stop the monitor. More...
 
bool is_running ()
 Check whether the monitor is running. More...
 
void add_event_type_filter (const fsw_event_type_filter &filter)
 Add an event type filter. More...
 
void set_event_type_filters (const std::vector< fsw_event_type_filter > &filters)
 Set the event type filters. More...
 
void set_watch_access (bool access)
 Monitor file access. More...
 

Protected Member Functions

bool accept_event_type (fsw_event_flag event_type) const
 Check whether an event should be accepted. More...
 
bool accept_path (const std::string &path) const
 Check whether a path should be accepted. More...
 
bool accept_path (const char *path) const
 Check whether a path should be accepted. More...
 
void notify_events (const std::vector< event > &events) const
 Notify change events. More...
 
void notify_overflow (const std::string &path) const
 Notify an overflow event. More...
 
std::vector< fsw_event_flagfilter_flags (const event &evt) const
 Filter event types. More...
 
virtual void run ()=0
 Execute monitor loop. More...
 
virtual void on_stop ()
 Execute an implementation-specific stop handler. More...
 

Protected Attributes

std::vector< std::string > paths
 List of paths to watch. More...
 
std::map< std::string, std::string > properties
 Map of custom properties. More...
 
FSW_EVENT_CALLBACKcallback
 Callback to which change events should be notified. More...
 
void * context = nullptr
 Pointer to context data that will be passed to the monitor::callback.
 
double latency = 1.0
 Latency of the monitor.
 
bool fire_idle_event = false
 If true, the monitor will notify an event when idle. More...
 
bool allow_overflow = false
 If true, queue overflow events will be notified to the caller, otherwise the monitor will throw a libfsw_exception.
 
bool recursive = false
 If true, directories will be scanned recursively.
 
bool follow_symlinks = false
 If true, symbolic links are followed.
 
bool directory_only = false
 Flag indicating whether only directories should be monitored.
 
bool watch_access = false
 Flag indicating whether file access should be watched.
 
bool running = false
 Flag indicating whether the monitor is in the running state.
 
bool should_stop = false
 Flag indicating whether the monitor should preemptively stop.
 
std::mutex run_mutex
 Mutex used to serialize access to the monitor state from multiple threads.
 
std::mutex notify_mutex
 Mutex used to serialize access to the notify_events() method.
 

Detailed Description

Base class of all monitors.

The fsw::monitor class is the base class of all monitors. This class encapsulates the common functionality of a monitor:

Since some methods are designed to be called from different threads, this class provides an internal mutex (monitor::run_mutex) that implementors should lock on when accessing shared state. The mutex is available only when HAVE_CXX_MUTEX is defined.

At least the following tasks must be performed to implement a monitor:

A basic monitor needs to implement the run() method, whose skeleton is often similar to the following:

void run()
{
  initialize_api();

  for (;;)
  {
    #ifdef HAVE_CXX_MUTEX
      unique_lock<mutex> run_guard(run_mutex);
      if (should_stop) break;
      run_guard.unlock();
    #endif

    scan_paths();
    wait_for_events();

    vector<change_events> evts = get_changes();
    vector<event> events;

    for (auto & evt : evts)
    {
      if (accept(evt.get_path))
      {
        events.push_back({event from evt});
      }
    }

    if (events.size()) notify_events(events);
  }

  terminate_api();
}

Despite being a minimal implementation, it performs all the tasks commonly performed by a monitor:

Constructor & Destructor Documentation

fsw::monitor::monitor ( std::vector< std::string >  paths,
FSW_EVENT_CALLBACK callback,
void *  context = nullptr 
)

Constructs a monitor watching the specified paths.

The monitor will notify change events to the specified callback, passing it the pointer to the specified context.

Parameters
pathsThe list of paths to watch.
callbackThe callback to which change events will be notified. The callback cannot be null, otherwise a libfsw_exception will be thrown.
contextAn optional pointer to context data. The monitor stores a copy of this pointer to pass it to the callback.
fsw::monitor::~monitor ( )
virtual

Destructs a monitor instance.

This destructor performs the following operations:

  • Stops the monitor.
  • Frees the compiled regular expression of the path filters, if any.
Warning
Destroying a monitor in the running state results in undefined behaviour.
See also
stop()

Member Function Documentation

bool fsw::monitor::accept_event_type ( fsw_event_flag  event_type) const
protected

Check whether an event should be accepted.

This function checks event_type against the event type filters of the monitor to determine whether it should be accepted.

Parameters
event_typeThe event type to check.
Returns
true if the event is accepted, false otherwise.
bool fsw::monitor::accept_path ( const std::string &  path) const
protected

Check whether a path should be accepted.

This function checks path against the path filters of the monitor to determine whether it should be accepted.

Parameters
event_typeThe path to check.
Returns
true if the path is accepted, false otherwise.
bool fsw::monitor::accept_path ( const char *  path) const
protected

Check whether a path should be accepted.

This function checks path against the path filters of the monitor to determine whether it should be accepted.

Parameters
event_typeThe path to check.
Returns
true if the path is accepted, false otherwise.
void fsw::monitor::add_event_type_filter ( const fsw_event_type_filter filter)

Add an event type filter.

Adds a fsw_event_type_filter instance to filter events by type.

Parameters
filterThe event type filter to add.
void fsw::monitor::add_filter ( const monitor_filter filter)

Add a path filter.

This function adds a monitor_filter instance instance to the filter list.

Parameters
filterThe filter to add.
vector< fsw_event_flag > fsw::monitor::filter_flags ( const event evt) const
protected

Filter event types.

This function filters the event types of an event leaving only the types allowed by the configured filters.

Parameters
evtThe event whose types must be filtered.
Returns
A vector containing the acceptable events.
void * fsw::monitor::get_context ( ) const

Get the pointer to the context data.

This function gets the pointer to the context data that is passed to the callback by the monitor.

Returns
The pointer to the context data.
string fsw::monitor::get_property ( std::string  name)

Gets the value of a property.

This method gets the value of the property name. If the property name is not set, this method returns an empty string.

Parameters
nameThe name of the property.
Returns
The value of the property.
bool fsw::monitor::is_running ( )

Check whether the monitor is running.

State is checked thread-safely locking on monitor::run_mutex.

Returns
true if the monitor is running, false otherwise.
void fsw::monitor::notify_events ( const std::vector< event > &  events) const
protected

Notify change events.

This function notifies change events using the provided callback.

See also
monitor()
void fsw::monitor::notify_overflow ( const std::string &  path) const
protected

Notify an overflow event.

This function notifies an overflow event using the provided callback.

Warning
Experiencing an overflow and the ability to notify it is an implementation-defined behaviour.
See also
monitor()
void fsw::monitor::on_stop ( )
protectedvirtual

Execute an implementation-specific stop handler.

This function is executed by the stop() method, after requesting the monitor to stop. This handler is required if the thread running run() is not able to preemptively stop its execution by checking the monitor::should_stop flag.

See also
stop()

Reimplemented in fsw::fsevents_monitor.

virtual void fsw::monitor::run ( )
protectedpure virtual

Execute monitor loop.

This function implements the monitor event watching logic. This function is called from start() and it is executed on its thread. This function should block until the monitoring loop terminates: when it returns, the monitor is marked as stopped.

This function should cooperatively check the monitor::should_stop field locking monitor::run_mutex and return if set to true.

See also
start()
stop()

Implemented in fsw::fen_monitor, fsw::inotify_monitor, fsw::kqueue_monitor, fsw::windows_monitor, fsw::fsevents_monitor, and fsw::poll_monitor.

void fsw::monitor::set_allow_overflow ( bool  overflow)

Notify buffer overflows as change events.

If this flag is set, the monitor will report a monitor buffer overflow as a change event of type fsw_event_flag::Overflow.

Warning
The behaviour associated with this flag depends on the implementation.
Parameters
overflowtrue if overflow should be notified, false otherwise.
void fsw::monitor::set_context ( void *  context)

Set the context data.

This function sets the pointer to the context data. The context data is opaque data that the monitor passes to the event callback.

Warning
The monitor stores the pointer to the context data throughout its life. The caller must ensure it points to valid data until the monitor is running.
Parameters
contextThe pointer to the context data.
void fsw::monitor::set_directory_only ( bool  directory_only)

Watch directories only.

This function sets the directory only flag to the specified value. If this flag is set, then the monitor will only watch directories during a recursive scan. This functionality is only supported by monitors whose backend fires change events on a directory when one its children is changed. If a monitor backend does not support this functionality, the flag is ignored.

Warning
The behaviour associated with this flag depends on the implementation.
Parameters
directory_onlytrue if only directories should be watched, flase otherwise.
void fsw::monitor::set_event_type_filters ( const std::vector< fsw_event_type_filter > &  filters)

Set the event type filters.

This function sets the list of event type filters, substituting existing filters if any.

Parameters
filtersThe filters to set.
void fsw::monitor::set_filters ( const std::vector< monitor_filter > &  filters)

Set the path filters.

This function sets the list of path filters, substituting existing filters if any.

Parameters
filtersThe filters to set.
void fsw::monitor::set_fire_idle_event ( bool  fire_idle_event)

Sets the fire idle event flag.

When true, the fire idle event flag instructs the monitor to fire a fake event at the event of an idle cycle. An idle cycle is a period of time whose length is 110% of the monitor::latency where no change events were detected.

Parameters
fire_idle_eventtrue if idle events should be fired, false otherwise.
void fsw::monitor::set_follow_symlinks ( bool  follow)

Follow symlinks.

This function sets the follow_symlinks flag of the monitor to indicate whether the monitor should follow symbolic links or observe the links themselves.

Warning
The behaviour associated with this flag depends on the implementation.
Parameters
followtrue if symbolic links should be followed, false otherwise.
void fsw::monitor::set_latency ( double  latency)

Sets the latency.

This method sets the latency of the monitor to latency. The latency is a positive number that indicates to a monitor implementation how often events must be retrieved or waited for: the shortest the latency, the quicker events are processed.

Warning
The behaviour associated with this flag depends on the implementation.
Parameters
latencyThe latency value.
void fsw::monitor::set_properties ( const std::map< std::string, std::string >  options)

Sets the custom properties.

This method replaces all the existing properties using the pairs contained into options.

Parameters
optionsThe map containing the properties to set.
void fsw::monitor::set_property ( const std::string &  name,
const std::string &  value 
)

Sets a custom property.

This method sets the custom property name to value.

Parameters
nameThe name of the property.
valueThe value of the property.
void fsw::monitor::set_recursive ( bool  recursive)

Recursively scan subdirectories.

This function sets the recursive flag of the monitor to indicate whether the monitor should recursively observe the contents of directories. The behaviour associated with this flag is an implementation-specific detail. This class only stores the value of the flag.

Warning
The behaviour associated with this flag depends on the implementation.
Parameters
recursivetrue if directories should be recursively, false otherwise.
void fsw::monitor::set_watch_access ( bool  access)

Monitor file access.

Warning
The ability of monitoring file access depends on a monitor implementation.
void fsw::monitor::start ( )

Start the monitor.

The monitor status is marked as running and it starts watching for change events. This function performs the following tasks:

This call does not return until the monitor is stopped and events are notified from its thread.

State changes are performed thread-safely locking on monitor::run_mutex.

See also
run()
stop()
void fsw::monitor::stop ( )

Stop the monitor.

This function asks the monitor to stop. Since start() is designed to execute the monitoring loop in its thread and to not return until the monitor is stopped, stop() is designed to be called from another thread. stop() is a cooperative signal that must be handled in an implementation-specific way in the run() function.

State changes are performed thread-safely locking on monitor::run_mutex.

See also
run()
start()

Member Data Documentation

FSW_EVENT_CALLBACK* fsw::monitor::callback
protected

Callback to which change events should be notified.

See also
monitor::monitor()
bool fsw::monitor::fire_idle_event = false
protected

If true, the monitor will notify an event when idle.

An idle cycle is long as 110% of the monitor::latency value.

std::vector<std::string> fsw::monitor::paths
protected

List of paths to watch.

See also
monitor::monitor()
std::map<std::string, std::string> fsw::monitor::properties
protected

Map of custom properties.

See also
monitor::set_property()
monitor::set_properties()

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