libfilezilla
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Classes | Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | Friends
final< UniqueType, Values > Class Template Reference

This is the recommended event class. More...

#include <event.hpp>

Inheritance diagram for final< UniqueType, Values >:
Inheritance graph
[legend]
Collaboration diagram for final< UniqueType, Values >:
Collaboration graph
[legend]

List of all members.

Classes

struct  final

Public Types

enum  mode { reading, writing }
 Files can be opened for reading or writing, but not both.
enum  creation_flags { existing, empty }
 Creation flags when opening file for writing. More...
enum  seek_mode { begin, current, end }
 Used by seek. More...
enum  type { unknown = -1, file, dir, link }
 Types of files. While 'everything is a file', a filename can refer to a file proper, a directory or a symbolic link.
enum  accuracy {
  days, hours, minutes, seconds,
  milliseconds
}
 The datetime's accuracy.
enum  zone { utc, local }
 When importing or exporting a timestamp, zone is used to explicitly specify whether the conversion is to/from localtime or UTC.
typedef UniqueType unique_type
typedef std::tuple< Values...> tuple_type
typedef std::deque< std::pair
< event_handler *, event_base * > > 
Events

Public Member Functions

 simple_event ()
template<typename First_Value , typename... Remaining_Values>
 simple_event (First_Value &&value, Remaining_Values &&...values)
 simple_event (simple_event const &op)
simple_event & operator= (simple_event const &op)
virtual void const * derived_type () const
 Simply returns type()
 event_loop ()
 Spawns a thread and starts the loop.
virtual ~event_loop ()
 Stops the thread.
 event_loop (event_loop const &)
event_loopoperator= (event_loop const &)
void filter_events (std::function< bool(Events::value_type &)> const &filter)
 Allows filtering of queued events.
void stop ()
 Stops the loop.
 file ()
 file (native_string const &f, mode m, creation_flags d=existing)
 file (file const &)
file & operator= (file const &)
bool opened () const
bool open (native_string const &f, mode m, creation_flags d=existing)
void close ()
int64_t size () const
 Gets size of file.
int64_t seek (int64_t offset, seek_mode m)
 Relative seek based on seek mode.
bool truncate ()
 Truncate the file to the current position of the file pointer.
int64_t read (void *buf, int64_t count)
 Read data from file.
int64_t write (void const *buf, int64_t count)
 Write data to file.
 local_filesys ()
 local_filesys (local_filesys const &)
local_filesys & operator= (local_filesys const &)
bool begin_find_files (native_string path, bool dirs_only=false)
 Begins enumerating a directory.
bool get_next_file (native_string &name)
 Gets the next file in the directory. Call until it returns false.
bool get_next_file (native_string &name, bool &is_link, bool &is_dir, int64_t *size, datetime *modification_time, int *mode)
void end_find_files ()
 Ends enumerating files. Automatically called in the destructor.
 mutex (bool recursive=true)
 mutex (mutex const &)
mutex & operator= (mutex const &)
void lock ()
 Beware, manual locking isn't exception safe, use scoped_lock.
void unlock ()
 Beware, manual locking isn't exception safe, use scoped_lock.
 scoped_lock (mutex &m)
 scoped_lock (scoped_lock const &)
scoped_lock & operator= (scoped_lock const &)
void lock ()
 Obtains the mutex.
void unlock ()
 Releases the mutex.
 condition ()
 condition (condition const &)
condition & operator= (condition const &)
void wait (scoped_lock &l)
 Wait indefinitely for condition to become signalled.
bool wait (scoped_lock &l, duration const &timeout)
 Wait until timeout for condition to become signalled.
void signal (scoped_lock &l)
 Signal condition variable.
bool signalled (scoped_lock const &) const
 Check if condition is already signalled.
 sparse_optional ()
 sparse_optional (T const &v)
 sparse_optional (T *v)
 Takes ownership of pointer.
 sparse_optional (sparse_optional< T > const &v)
 sparse_optional (sparse_optional< T > &&v) noexcept
void clear ()
 operator bool () const
T & operator* ()
T const & operator* () const
T * operator-> ()
T const * operator-> () const
bool operator== (sparse_optional< T > const &cmp) const
bool operator!= (sparse_optional< T > const &cmp) const
bool operator< (sparse_optional< T > const &cmp) const
sparse_optional< T > & operator= (sparse_optional< T > const &v)
sparse_optional< T > & operator= (sparse_optional< T > &&v) noexcept
 process ()
 process (process const &)
process & operator= (process const &)
bool spawn (native_string const &cmd, std::vector< native_string > const &args=std::vector< native_string >())
 Start the process.
void kill ()
 Stops the spawned process.
int read (char *buffer, unsigned int len)
 Read data from process.
bool write (char const *buffer, unsigned int len)
 Write data data process.
bool write (std::string const &s)
 shared_optional ()
 shared_optional (shared_optional< T, Init > const &v)
 shared_optional (shared_optional< T, Init > &&v) noexcept
 shared_optional (const T &v)
void clear ()
T & get ()
 Gets a reference to the stored object.
const T & operator* () const
const T * operator-> () const
shared_optional< T, Init > & operator= (shared_optional< T, Init > const &v)
shared_optional< T, Init > & operator= (shared_optional< T, Init > &&v) noexcept
 operator bool () const
bool empty () const
 async_task ()
 async_task (async_task const &)
async_task & operator= (async_task const &)
 async_task (async_task &&other) noexcept
async_task & operator= (async_task &&other) noexcept
void join ()
 Wait for the task to finish.
 operator bool () const
 Check whether it's a spawned, unjoined task.
 thread_pool ()
 thread_pool (thread_pool const &)
thread_pool & operator= (thread_pool const &)
async_task spawn (std::function< void()> const &f)
 Spawns a new asynchronous task.
 datetime ()
 A default-constructed timestamp is empty()
 datetime (zone z, int year, int month, int day, int hour=-1, int minute=-1, int second=-1, int millisecond=-1)
 datetime (time_t, accuracy a)
 datetime (std::string const &s, zone z)
 Construct from string, looks for YYYYmmDD[[[[HH]MM]SS]sss].
 datetime (std::wstring const &s, zone z)
 datetime (FILETIME const &ft, accuracy a)
 Windows-only: Construct from FILETIME.
 datetime (datetime const &op)
 datetime (datetime &&op) noexcept
datetimeoperator= (datetime const &op)
datetimeoperator= (datetime &&op) noexcept
bool empty () const
void clear ()
 Resulting timestamp is empty()
accuracy get_accuracy () const
int compare (datetime const &op) const
 Accuracy-aware comparison against another timestamp.
bool earlier_than (datetime const &op) const
 Equivalent to compare(op) < 0.
bool later_than (datetime const &op) const
 Equivalent to compare(op) > 0.
bool set (zone z, int year, int month, int day, int hour=-1, int minute=-1, int second=-1, int millisecond=-1)
 Sets the timestamp.
bool set (std::string const &str, zone z)
 Set from string, looks for YYYYmmDD[[[[HH]MM]SS]sss].
bool set (std::wstring const &str, zone z)
bool set (FILETIME const &ft, accuracy a)
 Windows-only: Set timestamp from FILETIME.
bool set (SYSTEMTIME const &ft, accuracy a, zone z)
 Windows-only: Set timestamp from SYSTEMTIME.
bool set (tm &t, accuracy a, zone z)
bool imbue_time (int hour, int minute, int second=-1, int millisecond=-1)
 Adds time to timestamps that only have a day-accuracy.
std::string format (std::string const &format, zone z) const
std::wstring format (std::wstring const &format, zone z) const
int get_milliseconds () const
 Get millisecond part of timestamp.
time_t get_time_t () const
 Get timestamp as time_t, seconds since 1970-01-01 00:00:00.
tm get_tm (zone z) const
 Get timestamp as struct tm.
FILETIME get_filetime () const
 Windows-only: Get timestamp as FILETIME.
 duration ()
duration & operator-= (duration const &op)
duration operator- () const
 operator bool () const
bool operator< (duration const &op) const
bool operator<= (duration const &op) const
bool operator> (duration const &op) const
bool operator>= (duration const &op) const
 monotonic_clock ()
 Constructs empty clock.
 monotonic_clock (monotonic_clock const &)
 monotonic_clock (monotonic_clock &&) noexcept
monotonic_clockoperator= (monotonic_clock const &)
monotonic_clockoperator= (monotonic_clock &&) noexcept
monotonic_clock const operator+ (duration const &d) const
 operator bool () const
monotonic_clockoperator+= (duration const &d)
monotonic_clockoperator-= (duration const &d)
Deep relational operators

If two instances point to different objects, those objects are compared. Empty instances are less than non-empty instances.

bool operator== (shared_optional< T, Init > const &cmp) const
bool operator== (T const &cmp) const
bool operator< (shared_optional< T, Init > const &cmp) const
bool operator< (T const &cmp) const
bool is_same (shared_optional< T, Init > const &cmp) const
 Only compares the pointers.
bool operator!= (const shared_optional< T, Init > &cmp) const
bool operator!= (T const &cmp) const
Naive comparison operators

Naive operators compare the timestamp's internal representation first, with accuracy as secondary criterion.

See also:
compare
bool operator== (datetime const &op) const
bool operator!= (datetime const &op) const
bool operator< (datetime const &op) const
bool operator<= (datetime const &op) const
bool operator> (datetime const &op) const
Adding/subtracting duration intervals

Adding or subracting a duration interval is accuracy-aware, e.g. adding a single second to a datetime with minute-accuracy does not change the timestamp.

datetimeoperator+= (duration const &op)
datetime operator+ (duration const &op) const
datetimeoperator-= (duration const &op)
datetime operator- (duration const &op) const
Getters

All getters return the total time of the duration, rounded down to the requested granularity.

int64_t get_days () const
int64_t get_hours () const
int64_t get_minutes () const
int64_t get_seconds () const
int64_t get_milliseconds () const

Static Public Member Functions

static void const * type ()
 Returns a unique pointer for the type such that can be used directly in derived_type.
static bool is_separator (wchar_t c)
 Checks whether given character is a path separator.
static type get_file_type (native_string const &path, bool follow_links=false)
 GetFileType return the type of the passed path.
static type get_file_info (native_string const &path, bool &is_link, int64_t *size, datetime *modification_time, int *mode)
static int64_t get_size (native_string const &path, bool *is_link=0)
 Gets size of file, returns -1 on error.
static datetime get_modification_time (native_string const &path)
static bool set_modification_time (native_string const &path, const datetime &t)
static native_string get_link_target (native_string const &path)
 Get the target path of a symbolic link.
static datetime now ()
 Returns the current date/time.
static bool verify_format (std::string const &fmt)
static bool verify_format (std::wstring const &fmt)
static duration from_days (int64_t m)
static duration from_hours (int64_t m)
static duration from_minutes (int64_t m)
static duration from_seconds (int64_t m)
static duration from_milliseconds (int64_t m)
static monotonic_clock now ()
 Gets the current point in time time.

Public Attributes

tuple_type v_
 The event value, gets built from the arguments passed in the constructur.

Static Public Attributes

static char const path_separator
 The system's preferred path separator.

Friends

class event_handler
class condition
class scoped_lock
class thread_pool
class pooled_thread_impl
class async_task
duration operator- (datetime const &a, datetime const &b)
 Gets the difference between two timestamps as duration.
duration operator- (duration const &a, duration const &b)
duration operator- (monotonic_clock const &a, monotonic_clock const &b)
bool operator== (monotonic_clock const &a, monotonic_clock const &b)
bool operator< (monotonic_clock const &a, monotonic_clock const &b)
bool operator<= (monotonic_clock const &a, monotonic_clock const &b)
bool operator> (monotonic_clock const &a, monotonic_clock const &b)
bool operator>= (monotonic_clock const &a, monotonic_clock const &b)

Detailed Description

template<typename UniqueType, typename... Values>
class fz::final< UniqueType, Values >

This is the recommended event class.

A monotonic clock (aka steady clock) is independent from walltime.

The duration class represents a time interval in milliseconds.

Represents a point of time in wallclock, tracking the timestamps accuracy/precision.

A dumb thread-pool for asynchronous tasks.

Handle for asynchronous tasks.

shared_optional is like std::shared_ptr but with relational operators acting like C++17's std::optional

The process class manages an asynchronous process with redirected IO.

Similar to C++17's std::optional, but stores the data in dynamic memory.

Waitable condition variable.

A simple scoped lock.

Lean replacement for std::(recursive_)mutex.

This class can be used to enumerate the contents of local directories and to query the metadata of files.

Lean class for file access.

A threaded event loop that supports sending events and timers.

Instanciate the template with a unique type to identify the type of the event and a number of types for the values.

Keep the values simple, in particular avoid mutexes in your values.

See also:
event_handler for usage example.

Timers have precedence over queued events. Too many or too frequent timers can starve processing queued events.

If the deadlines of multiple timers have expired, they get processed in an unspecified order.

See also:
event_handler for a complete usage example.

This class uses the system's native file access functions. It is a less convoluted and much faster alternative to the almost useless std::fstream.

Supports large files exceeding the 32bit limits.

This class is aware of symbolic links. Under Windows it can handle reparse points as well.

Unfortunately we can't use std::mutex and std::condition_variable as MinGW doesn't implement C++11 threading yet. Even in those variants that at least mutexes and condition variables, they doen't make use of Vista+'s CONDITION_VARIABLE, so it's too slow for our needs.

Note:
Once all platforms have C++11 threading implemented _in the fastest way possible_, this class will be removed.

The lock is aquired on construction and, if still locked, released on destruction. You can manually unlock and re-lock if needed.

Note:
While this can be used with recursive mutexes, scoped_lock does not implement reference counting.

Allows one thread to wait for the condition variable to become signalled by another thread.

sparse_optional is useful to save memory if it is expected that the object is rarely set and the object's size is bigger than a simple pointer.

No console window is being created.

To use, spawn the process and, since it's blocking, call read from a different thread.

Template Parameters:
Tthat can be stored in the shared_optional
Initcontrols whether the optional can be empty. If false, the default, it acts like a normal optional/shared_ptr. If true, it can never be empty.
See also:
shared_value

This class is thread-safe under the following assumptions:

If there are no idle threads, threads are created on-demand if spawning an asynchronous task. Once an asynchronous task finishes, the corresponding thread is kept idle until the pool is destroyed.

Any number of tasks can be run concurrently.

As time may come from different sources that have different accuracy/precision, this class keeps track of accuracy information.

For example, your local filesystem might store timestamps with milliseconds, whereas a given network protocol might only offer seconds. You can use compare to easily check whether the timestamp of a local file is equivalent to a timestamp received via the protocol.

The internal representation of datetime is in milliseconds since 1970-01-01 00:00:00.000 UTC and can handle a range of several million years. While datetime supports negative times (i.e. earlier than 1970-01-01 00:00:00.000 UTC), the underlying plaform may not support it.

Remarks:
Some *nix systems base their time on TAI instead of UTC, though we pretend there is no difference, as the latter is the default on every modern distribution.

Constructing a non-empty duration is only possible using the static setters which have the time unit as part of the function name.

In contract to datetime, duration does not track accuracy.

In particular, while wallclock might jump forward and backward (e.g. due to DST), the monotonic clock ticks steadily forward at always the same pace.

monotonic_clock is a convenience wrapper around std::chrono::steady_clock.


Member Enumeration Documentation

Creation flags when opening file for writing.

Only evaluated when opening existing files for writing Non-existing files will always be created when writing. Opening for reading never creates files.

Enumerator:
existing 

Keep existing data if file exists, otherwise create new.

empty 

Truncate file if already existing, otherwise create new.

enum seek_mode

Used by seek.

Enumerator:
begin 

Seek from beginning of file.

current 

Seek from current position in the file.

end 

Seek from end of file.


Member Function Documentation

bool begin_find_files ( native_string  path,
bool  dirs_only = false 
)

Begins enumerating a directory.

Parameters:
dirs_onlyIf true, only directories are enumerated.
int compare ( datetime const &  op) const

Accuracy-aware comparison against another timestamp.

Conceptually it works as if naively comparing both timestamps after truncating/clamping them to the least common accuracy.

Returns:
0 if timestamps are equivalent,
<0 if own timestamp is earlier than the argument,
>0 if own timestamp is late than the argument.
datetime ( std::string const &  s,
zone  z 
) [explicit]

Construct from string, looks for YYYYmmDD[[[[HH]MM]SS]sss].

See also:
bool set(std::string const& str, zone z)
bool empty ( ) const
Returns:
true if no timestamp has been set
void filter_events ( std::function< bool(Events::value_type &)> const &  filter)

Allows filtering of queued events.

Puts all queued events through the filter function. The filter function can freely change the passed events. If the filter function returns true, the corresponding event gets removed.

The filter function must not call any function of event_loop.

Filtering events is a blocking operation and temporarily pauses the loop.

std::string format ( std::string const &  format,
zone  z 
) const

Format time as string

Parameters:
formatis a format string as understood by ::strftime
T& get ( )

Gets a reference to the stored object.

A new object is created it if is not set. Returned reference is unique, it is not shared.

static type get_file_info ( native_string const &  path,
bool &  is_link,
int64_t *  size,
datetime modification_time,
int *  mode 
) [static]

Gets the info for the passed arguments. Follows symbolic links and stats the target, sets is_link to true if path was a link.

static type get_file_type ( native_string const &  path,
bool  follow_links = false 
) [static]

GetFileType return the type of the passed path.

Can optionally follow symbolic links.

bool get_next_file ( native_string name,
bool &  is_link,
bool &  is_dir,
int64_t *  size,
datetime modification_time,
int *  mode 
)

Gets the next file in the directory. Call until it returns false.

Stores the metadata in any non-null arguments.

bool imbue_time ( int  hour,
int  minute,
int  second = -1,
int  millisecond = -1 
)

Adds time to timestamps that only have a day-accuracy.

Changes accuracy based on given parameters. Use -1 in parameters that aren't used.

Returns:
Whether the function succeeded. On failure object remains unchanged.
static bool is_separator ( wchar_t  c) [inline, static]

Checks whether given character is a path separator.

On most systems, the forward slash is the only separator. The exception is Windows where both forward and backward slashes are separators, with the latter being preferred.

void kill ( )

Stops the spawned process.

This function doesn't actually kill the process, it merely closes the pipes.

Blocks until the process has quit.

void lock ( ) [inline]

Obtains the mutex.

Locking an already locked scoped_lock results in undefined behavior.

Constructs empty clock.

Comparisons with empty clocks and adding durations to an empty clocks are undefined.

int read ( char *  buffer,
unsigned int  len 
)

Read data from process.

This function blocks

Returns:
>0 Number of octets read, can be less than requested
0 on EOF
-1 on error.
int64_t read ( void *  buf,
int64_t  count 
)

Read data from file.

Reading from file advances the file pointer with the number of octets read.

Parameters:
bufThe buffer that should receive the data. Must be large enough to hold at least count octets
countThe number of octets to read
Returns:
>0 The number of octets read and placed into buf. It may be less than count.
0 at EOF
-1 on error
Note:
Reading less than count octets can happen at any time, it does not indicate EOF.
int64_t seek ( int64_t  offset,
seek_mode  m 
)

Relative seek based on seek mode.

It is possible to seek past the end of the file. Doing so does not change the size of the file. It will only change on subsequent writes.

You can get the current position int the file by passing current as seek_mode with a 0 offset.

Returns:
-1 on error, otherwise new absolute offset in file
Note:
On failure, the new position in the file is undefined.
bool set ( zone  z,
int  year,
int  month,
int  day,
int  hour = -1,
int  minute = -1,
int  second = -1,
int  millisecond = -1 
)

Sets the timestamp.

Parameters:
month1-indexed as on a calender, e.g. February is 2
day1-indexed as on a calender
hour0-indexed as on a 24h clock
Returns:
whether setting the timestamp succeeded. On failure object gets cleared
bool set ( std::string const &  str,
zone  z 
)

Set from string, looks for YYYYmmDD[[[[HH]MM]SS]sss].

Ignores all non-digit characters between fields. For example 20140720T165432 is the same as 2014-07-20 16:54:32

accuracy is set according to the fields present in the string.

Returns:
whether setting the timestamp succeeded. On failure object gets cleared
bool set ( tm &  t,
accuracy  a,
zone  z 
)

Sets timestamp from struct tm.

Note:
Not available on Windows.
Warning:
modifies passed structure
Returns:
true on success, false on failure. The object is empty after failure.
void signal ( scoped_lock &  l)

Signal condition variable.

To avoid race conditions leading to lost signals, you must pass a locked mutex.

Note:
Spurious signals are a rare possibility.
The lock must have be on the same mutex that is used for both signalling and for waiting.
bool signalled ( scoped_lock const &  ) const [inline]

Check if condition is already signalled.

To avoid race conditions leading to lost signals, you must pass a locked mutex.

Note:
The lock must have be on the same mutex that is used for both signalling and for waiting.
int64_t size ( ) const

Gets size of file.

Returns:
Size of file or -1 on error
bool spawn ( native_string const &  cmd,
std::vector< native_string > const &  args = std::vector< native_string >() 
)

Start the process.

This function takes care of properly quoting and escaping the the program's path and its arguments. Fails if process has already been spawned.

Parameters:
cmdThe path of the program to execute
argsThe command-line arguments for the process.
Note:
May return true even if the process cannot be started. In that case, trying to read from the process will fail with an error or EOF.
void stop ( )

Stops the loop.

Stops the event loop. It is automatically called by the destructor.

bool truncate ( )

Truncate the file to the current position of the file pointer.

Despite its name, this function can extend the size of the file if the current file pointer is past the end of the file.

void unlock ( ) [inline]

Releases the mutex.

Releasing a scoped_lock that isn't locked results in undefined behavior.

static bool verify_format ( std::string const &  fmt) [static]

Verify format strings

Parameters:
fmtthe string that is to be tested
Returns:
whether the passed string is a format string understood by ::strftime
void wait ( scoped_lock &  l)

Wait indefinitely for condition to become signalled.

Atomically unlocks the mutex and waits for the condition. Atomically consumes the signal and re-locks the mutex.

Note:
The lock must have be on the same mutex that is used for both signalling and for waiting.
bool wait ( scoped_lock &  l,
duration const &  timeout 
)

Wait until timeout for condition to become signalled.

Atomically unlocks the mutex and waits for the condition. Atomically consumes the signal and re-locks the mutex.

Returns:
true if the condition has been signalled.
false if the condition could not be obtained before the timeout has elapsed.
Note:
Spurious signals are a rare possibility.
The lock must have be on the same mutex that is used for both signalling and for waiting.
bool write ( char const *  buffer,
unsigned int  len 
)

Write data data process.

This function blocks

Returns:
true if all octets have been written.
false on error.
int64_t write ( void const *  buf,
int64_t  count 
)

Write data to file.

Writing to file advances the file pointer with the number of octets written

Parameters:
bufThe buffer that holds the data to be written. Must hold at least count octets
countThe number of octets to write
Returns:
>=0 The number of octets written to the file. It may be less than count.
-1 on error

Friends And Related Function Documentation

duration operator- ( datetime const &  a,
datetime const &  b 
) [friend]

Gets the difference between two timestamps as duration.

This function ignores accuracy, it treats both timestamps as if they had millisecond-accuracy.

duration operator- ( monotonic_clock const &  a,
monotonic_clock const &  b 
) [friend]

Gets the difference between two clocks as duration


Member Data Documentation

tuple_type v_

The event value, gets built from the arguments passed in the constructur.

You don't need to access this member directly if you use the dispatch mechanism.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines