qb::io::async::file_watcher< _Derived > Class Template Reference

CRTP base class for watching a single file for attribute changes and processing its contents. More...

#include <io.h>

Inheritance diagram for qb::io::async::file_watcher< _Derived >:

Collaboration diagram for qb::io::async::file_watcher< _Derived >:

Public Types
using	base_io_t = file_watcher<_Derived>
	Base I/O type alias for CRTP.

Public Member Functions
	file_watcher ()=default
	Default constructor.
	file_watcher (IProtocol *protocol) noexcept
	Constructor with an externally managed protocol.
	file_watcher (file_watcher const &)=delete
	Deleted copy constructor to prevent unintended copying of watcher state and resources.
	~file_watcher () noexcept
	Destructor.
template<typename _Protocol, typename... _Args>
_Protocol *	switch_protocol (_Args &&...args)
	Switches to a new protocol for processing file contents, taking ownership.
void	start (std::string const &fpath, ev_tstamp ts=0.1) noexcept
	Starts watching a file for attribute changes.
void	disconnect () noexcept
	Stops watching the file.
int	read_all ()
	Reads all available data from the file and processes it using the current protocol.

Static Public Attributes
static constexpr const bool	do_read = true
	Flag indicating this watcher type reads file content.

Additional Inherited Members
Protected Member Functions inherited from qb::io::async::base< file_watcher< _Derived >, event::file >
	base ()
	Constructor that registers the event watcher with the current listener.
	~base ()
	Destructor that unregisters the event watcher.
Protected Attributes inherited from qb::io::async::base< file_watcher< _Derived >, event::file >
event::file &	_async_event
	Reference to the registered libev-based event watcher.

Detailed Description

template<typename _Derived>
class qb::io::async::file_watcher< _Derived >

CRTP base class for watching a single file for attribute changes and processing its contents.

This template class uses an event::file (which wraps ev::stat) to monitor a specified file path for changes in its attributes (e.g., size, modification time). When changes are detected, it can read the file content and process it using a AProtocol.

Template Parameters

_Derived

The derived class type (CRTP pattern) that implements transport-specific read operations and handles protocol messages and file events.

Constructor & Destructor Documentation

file_watcher() [1/2]

template<typename _Derived>

qb::io::async::file_watcher< _Derived >::file_watcher ( )

default

Default constructor.

Initializes the file_watcher without a specific protocol. A protocol can be set later using switch_protocol.

file_watcher() [2/2]

template<typename _Derived>

qb::io::async::file_watcher< _Derived >::file_watcher ( IProtocol * protocol )

inlinenoexcept

Constructor with an externally managed protocol.

Parameters

protocol

Pointer to an existing protocol instance. This file_watcher will use it but not take ownership unless it's the same instance later set via switch_protocol which would then add it to _protocol_list. If ownership by file_watcher is desired from construction, prefer using switch_protocol after default construction.

~file_watcher()

template<typename _Derived>

qb::io::async::file_watcher< _Derived >::~file_watcher ( )

inlinenoexcept

Destructor.

Cleans up all protocol instances created and owned by this file_watcher (i.e., those added to _protocol_list via switch_protocol).

Member Function Documentation

switch_protocol()

template<typename _Derived>

template<typename _Protocol, typename... _Args>

_Protocol * qb::io::async::file_watcher< _Derived >::switch_protocol ( _Args &&... args )

inline

Switches to a new protocol for processing file contents, taking ownership.

Template Parameters

_Protocol	The concrete AProtocol type to instantiate.
_Args	Argument types for the _Protocol constructor.

Parameters

args	Arguments to forward to the _Protocol constructor.

Returns

Pointer to the newly created and activated protocol instance if successful (protocol's ok() returns true), otherwise nullptr (and the created protocol is deleted).

Any previously owned protocol is not deleted by this method. The new protocol instance is added to an internal list and will be cleaned up by the file_watcher destructor. The current active protocol is set to this new instance.

start()

template<typename _Derived>

void qb::io::async::file_watcher< _Derived >::start ( std::string const & fpath, ev_tstamp ts = 0.1 )

inlinenoexcept

Starts watching a file for attribute changes.

Parameters

fpath	Path to the file to watch.
ts	Polling interval in seconds. Libev uses this to check for changes. A smaller interval means more responsive but higher CPU usage. Default is 0.1 seconds.

Initializes and starts the underlying ev::stat watcher for the specified file. The on(event::file&) handler will be called when changes are detected.

disconnect()

template<typename _Derived>

void qb::io::async::file_watcher< _Derived >::disconnect ( )

inlinenoexcept

Stops watching the file.

Stops the underlying ev::stat watcher. No more file events will be generated for this path. The associated file descriptor in the transport is typically not closed by this call alone.

read_all()

template<typename _Derived>

int qb::io::async::file_watcher< _Derived >::read_all ( )

inline

Reads all available data from the file and processes it using the current protocol.

Returns

0 on success (all data read and processed, or file unchanged and no data to read). -1 if a read error occurs, or if the protocol becomes invalid, or if _Derived::read() fails.

This method is typically called from the on(event::file&) handler when a change is detected (e.g. file size increased). It repeatedly calls _Derived::read() to fill the input buffer, then processes messages via _protocol->getMessageSize() and _protocol->onMessage(). It also invokes _Derived::eof() and potentially _Derived::on(event::pending_read&) or _Derived::on(event::eof&) based on the read outcome and buffer state.

Note

Requires _Derived::do_read to be true (which it is for file_watcher by default). Assumes _protocol is not null if messages are expected.