Asynchronously watches a path for changes, then notifies a callback function when a change occurs. More...

#include <file_watcher.hpp>

Public Types
enum	file_action { CREATED = 0, CHANGED = 1, DELETED = 2 }
	The actions that file_watcher can monitor. More...
typedef boost::function< void(file_action action, const std::string &path)>	callback_t
Public Member Functions
	file_watcher (int sleep_ms=500)
	~file_watcher ()
	Destructor.
void	insert (const std::string &path, const callback_t &callback, bool call_now=false)
	Adds path to the list of monitored paths.
void	erase (const std::string &path)
	Removes path from the list of monitored paths.
void	start ()
	Starts the asynchronous monitor thread.
void	stop ()
	Stops the asynchronous monitor thread.
Private Member Functions
std::time_t	last_write_time (const boost::filesystem::path &p)
	we cannot assume that if a file exists, it will exist in the following moment that we check its file size
void	run ()
	Entry point for the asynchronous monitor thread.
Private Attributes
std::map< std::string, callback_t >	m_file_callback
	The map that associates watched files to the callbacks that should be launched.
std::map< std::string, std::pair< time_t, time_t > >	m_file_modified
	The map that associates watched files with their last known modification times.
boost::mutex	m_file_mutex
	Mutex to make modifications to file_watcher::m_file_callback and file_watcher::m_file_modified thread-safe.
boost::shared_ptr< boost::thread >	m_pthread
	Shared pointer to the thread that is constantly checking the files for modifications.
bool	m_run
	Whether the watcher thread is running.
boost::mutex	m_run_mutex
	Mutex that must be locked when we are changing file_watcher::m_run.
boost::condition	m_run_cond
	Condition to notify threads blocking on the file_watcher watcher thread.
int	m_sleep_ms

Detailed Description

Asynchronously watches a path for changes, then notifies a callback function when a change occurs.

file_watcher will notify you if a path is created, changed, or deleted.

After a file_watcher is instantiated, you must call file_watcher::start() to start up the asynchronous thread.

Definition at line 64 of file file_watcher.hpp.

Member Typedef Documentation

typedef boost::function<void(file_action action, const std::string & path)> moost::io::file_watcher::callback_t

Definition at line 76 of file file_watcher.hpp.

Member Enumeration Documentation

enum moost::io::file_watcher::file_action

The actions that file_watcher can monitor.

Enumerator:

CREATED	File creation.
CHANGED	File modification.
DELETED	File deletion.

Definition at line 69 of file file_watcher.hpp.

Constructor & Destructor Documentation

moost::io::file_watcher::file_watcher ( int sleep_ms = 500 ) [inline]

Constructs an empty file_watcher that is not running and not watching anything

Parameters:

sleep_ms,: the number of milliseconds to sleep in between checking files

Definition at line 142 of file file_watcher.hpp.

moost::io::file_watcher::~file_watcher ( ) [inline]

Destructor.

This method takes care of properly setting file_watcher::m_run to false using the file_watcher::m_run_mutex mutex, and it also waits until the watcher thread exits.

Definition at line 153 of file file_watcher.hpp.

Here is the call graph for this function:

Member Function Documentation

void moost::io::file_watcher::erase ( const std::string & path ) [inline]

Removes path from the list of monitored paths.

Parameters:

path	the path to stop monitoring

Definition at line 191 of file file_watcher.hpp.

Here is the caller graph for this function:

void moost::io::file_watcher::insert	(	const std::string &	path,
		const callback_t &	callback,
		bool	call_now = `false`
	)		`[inline]`

Adds path to the list of monitored paths.

Parameters:

path	the path to monitor
callback	the callback to notify if the path changes
call_now	will invoke the callback now

Definition at line 163 of file file_watcher.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

std::time_t moost::io::file_watcher::last_write_time ( const boost::filesystem::path & p ) [inline, private]

we cannot assume that if a file exists, it will exist in the following moment that we check its file size

Definition at line 119 of file file_watcher.hpp.

Here is the caller graph for this function:

void moost::io::file_watcher::run ( ) [inline, private]

Entry point for the asynchronous monitor thread.

Todo:: This could cause problems with frequent writing. We should really use boost.interprocess file locking instead (when we get 1.36 everywhere)

Definition at line 233 of file file_watcher.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void moost::io::file_watcher::start ( ) [inline]

Starts the asynchronous monitor thread.

Exceptions:

std::invalid_argument if the thread is already started

Definition at line 202 of file file_watcher.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void moost::io::file_watcher::stop ( ) [inline]

Stops the asynchronous monitor thread.

Exceptions:

std::invalid_argument if the thread is already stopped

Definition at line 215 of file file_watcher.hpp.

Here is the caller graph for this function:

Member Data Documentation

std::map<std::string, callback_t > moost::io::file_watcher::m_file_callback [private]

The map that associates watched files to the callbacks that should be launched.

Definition at line 81 of file file_watcher.hpp.

std::map<std::string, std::pair<time_t, time_t> > moost::io::file_watcher::m_file_modified [private]

The map that associates watched files with their last known modification times.

We actually track the last two modification times. Ideally, we want to send a notification only when the file was modified and the modifying process already closed the file, therefore we fire a CHANGED event only if the previous previous modification time is different from the previous modification time but the previous modification time equals the modification time we read from the file. Otherwise we just "shift" the pair (drop the previous previous modification, move the previous to the first position that is empty and push the file's last modification obtained from the filesystem to the second element of the pair).

Definition at line 93 of file file_watcher.hpp.

boost::mutex moost::io::file_watcher::m_file_mutex [private]

Mutex to make modifications to file_watcher::m_file_callback and file_watcher::m_file_modified thread-safe.

Definition at line 97 of file file_watcher.hpp.

boost::shared_ptr< boost::thread> moost::io::file_watcher::m_pthread [private]

Shared pointer to the thread that is constantly checking the files for modifications.

Definition at line 100 of file file_watcher.hpp.

bool moost::io::file_watcher::m_run [private]

Whether the watcher thread is running.

Definition at line 106 of file file_watcher.hpp.

boost::condition moost::io::file_watcher::m_run_cond [private]

Condition to notify threads blocking on the file_watcher watcher thread.

Definition at line 114 of file file_watcher.hpp.

boost::mutex moost::io::file_watcher::m_run_mutex [private]

Mutex that must be locked when we are changing file_watcher::m_run.

This is because file_watcher::m_run can be modified from the watcher thread itself and also from the thread that originally constructed this file_watcher.

Definition at line 112 of file file_watcher.hpp.

int moost::io::file_watcher::m_sleep_ms [private]

Definition at line 116 of file file_watcher.hpp.

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

/home/mhx/git/github/libmoost/include/moost/io/file_watcher.hpp

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation