From 2fafb13eaa30981754a8cd0ba8f3c082e3147fa8 Mon Sep 17 00:00:00 2001 From: Aaron Gyes Date: Sun, 5 Jun 2016 21:30:24 -0700 Subject: Be a bit more consistent and proper. --- src/autoload.cpp | 19 +++++++-------- src/autoload.h | 70 ++++++++++++++++++++++++------------------------------ src/wcstringutil.h | 14 +++++------ 3 files changed, 46 insertions(+), 57 deletions(-) (limited to 'src') diff --git a/src/autoload.cpp b/src/autoload.cpp index 9a8ebf40..56292fc6 100644 --- a/src/autoload.cpp +++ b/src/autoload.cpp @@ -22,7 +22,7 @@ #include "exec.h" #include "wutil.h" // IWYU pragma: keep -// The time before we'll recheck an autoloaded file. +/// The time before we'll recheck an autoloaded file. static const int kAutoloadStalenessInterval = 15; file_access_attempt_t access_file(const wcstring &path, int mode) { @@ -135,8 +135,9 @@ bool autoload_t::has_tried_loading(const wcstring &cmd) { return func != NULL; } +/// @return Whether this function is stale. +/// Internalized functions can never be stale. static bool is_stale(const autoload_function_t *func) { - // Return whether this function is stale. Internalized functions can never be stale. return !func->is_internalized && time(NULL) - func->access.last_checked > kAutoloadStalenessInterval; } @@ -159,14 +160,12 @@ autoload_function_t *autoload_t::get_autoloaded_function_with_creation(const wcs /// This internal helper function does all the real work. By using two functions, the internal /// function can return on various places in the code, and the caller can take care of various /// cleanup work. -/// -/// cmd: the command name ('grep') -/// really_load: whether to actually parse it as a function, or just check it it exists -/// reload: whether to reload it if it's already loaded -/// path_list: the set of paths to check -/// -/// Result: if really_load is true, returns whether the function was loaded. Otherwise returns -/// whether the function existed. +/// @param cmd the command name ('grep') +/// @param really_load Whether to actually parse it as a function, or just check it it exists +/// @param reload Whether to reload it if it's already loaded +/// @param path_list The set of paths to check +/// @return If really_load is true, returns whether the function was loaded. Otherwise returns +/// whether the function existed. bool autoload_t::locate_file_and_maybe_load_it(const wcstring &cmd, bool really_load, bool reload, const wcstring_list_t &path_list) { // Note that we are NOT locked in this function! diff --git a/src/autoload.h b/src/autoload.h index ef55fd94..efa8c16d 100644 --- a/src/autoload.h +++ b/src/autoload.h @@ -11,17 +11,17 @@ #include "common.h" #include "lru.h" -/// Recording an attempt to access a file. +/// Record of an attempt to access a file. struct file_access_attempt_t { - /// modification time of the file + /// Modification time of the file time_t mod_time; - /// when we last checked the file + /// When we last checked the file time_t last_checked; - /// whether we believe we could access this file + /// Whether or not we believe we can access this file bool accessible; - /// whether the access attempt is stale + /// The access attempt is stale bool stale; - /// if we could not access the file, the error code + /// If we cannot access the file, the error code encountered. int error; }; file_access_attempt_t access_file(const wcstring &path, int mode); @@ -33,9 +33,10 @@ struct autoload_function_t : public lru_node_t { is_loaded(false), is_placeholder(false), is_internalized(false) {} - /// the last access attempt + + /// The last access attempt recorded file_access_attempt_t access; - /// whether we have actually loaded this function + /// Have we actually loaded this function? bool is_loaded; /// Whether we are a placeholder that stands in for "no such function". If this is true, then /// is_loaded must be false. @@ -51,24 +52,23 @@ struct builtin_script_t { class env_vars_snapshot_t; -/// A class that represents a path from which we can autoload, and the autoloaded contents. +/// Class representing a path from which we can autoload and the autoloaded contents. class autoload_t : private lru_cache_t { private: - // Lock for thread safety. + /// Lock for thread safety. pthread_mutex_t lock; - // The environment variable name. + /// The environment variable name. const wcstring env_var_name; - // Builtin script array. + /// Builtin script array. const struct builtin_script_t *const builtin_scripts; - // Builtin script count. + /// Builtin script count. const size_t builtin_script_count; - // The path from which we most recently autoloaded. + /// The path from which we most recently autoloaded. wcstring last_path; - // That path, tokenized (split on separators). + /// the most reecently autoloaded path, tokenized (split on separators). wcstring_list_t last_path_tokenized; - - // A table containing all the files that are currently being loaded. This is here to help - // prevent recursion. + /// A table containing all the files that are currently being loaded. + /// This is here to help prevent recursion. std::set is_loading_set; void remove_all_functions(void) { this->evict_all_nodes(); } @@ -82,39 +82,31 @@ class autoload_t : private lru_cache_t { bool allow_eviction); protected: - // Overridable callback for when a command is removed. + /// Overridable callback for when a command is removed. virtual void command_removed(const wcstring &cmd) {} public: - // Create an autoload_t for the given environment variable name. + /// Create an autoload_t for the given environment variable name. autoload_t(const wcstring &env_var_name_var, const builtin_script_t *scripts, size_t script_count); - virtual ~autoload_t(); // destructor - - // Autoload the specified file, if it exists in the specified path. Do not load it multiple - // times unless its timestamp changes or parse_util_unload is called. - // - // Autoloading one file may unload another. - // - // \param cmd the filename to search for. The suffix '.fish' is always added to this name - // \param on_unload a callback function to run if a suitable file is found, which has not - // already been run. unload will also be called for old files which are unloaded. - // \param reload wheter to recheck file timestamps on already loaded files + virtual ~autoload_t(); + + /// Autoload the specified file, if it exists in the specified path. Do not load it multiple + /// times unless its timestamp changes or parse_util_unload is called. + /// Autoloading one file may unload another. + /// @param cmd the filename to search for. The suffix '.fish' is always added to this name + /// @param reload wheter to recheck file timestamps on already loaded files int load(const wcstring &cmd, bool reload); - // Check whether we have tried loading the given command. Does not do any I/O. + /// Check whether we have tried loading the given command. Does not do any I/O. bool has_tried_loading(const wcstring &cmd); - // Tell the autoloader that the specified file, in the specified path, is no longer loaded. - // - // \param cmd the filename to search for. The suffix '.fish' is always added to this name - // \param on_unload a callback function which will be called before (re)loading a file, may be - // used to unload the previous file. - // \return non-zero if the file was removed, zero if the file had not yet been loaded + /// Tell the autoloader that the specified file, in the specified path, is no longer loaded. + /// Returns non-zero if the file was removed, zero if the file had not yet been loaded int unload(const wcstring &cmd); - // Check whether the given command could be loaded, but do not load it. + /// Check whether the given command could be loaded, but do not load it. bool can_load(const wcstring &cmd, const env_vars_snapshot_t &vars); }; #endif diff --git a/src/wcstringutil.h b/src/wcstringutil.h index ea4489e7..4a86f86e 100644 --- a/src/wcstringutil.h +++ b/src/wcstringutil.h @@ -7,18 +7,16 @@ #include "common.h" -/// Typedef that represents a range in a wcstring. The first element is the location, the second is -/// the count. +/// @typedef wcstring_range represents a range in a wcstring. +/// The first element is the location, the second is the count. typedef std::pair wcstring_range; /// wcstring equivalent of wcstok(). Supports NUL. For convenience and wcstok() compatibility, the /// first character of each token separator is replaced with NUL. -/// -/// Returns a pair of (pos, count). -/// Returns (npos, npos) when it's done. -/// Returns (pos, npos) when the token is already known to be the final token. -/// -/// Note that the final token may not necessarily return (pos, npos). +/// @return Returns a pair of (pos, count). +/// This will be (npos, npos) when it's done. In the form of (pos, npos) +/// when the token is already known to be the final token. +/// @note The final token may not necessarily return (pos, npos). wcstring_range wcstring_tok(wcstring& str, const wcstring& needle, wcstring_range last = wcstring_range(0, 0)); -- cgit v1.2.3