fx.c File Reference

Definitions for integration with the experiment-running system. More...

Include dependency graph for fx.c:

Go to the source code of this file.

Defines

#define FX__BUF_SIZE   (3 * (sizeof(long long) > 8 ? sizeof(long long) : 8))
#define FX__FATAL(prefix, entry, msg_params...)
#define FX__NONFATAL(prefix, entry, msg_params...)
#define FX__SEMIFATAL(success, prefix, entry, msg_params...)

Functions

void fx_clear_param (fx_module *mod, const char *key)
 Unsets a parameter's value, effectively removing the entry.
void fx_clear_result (fx_module *mod, const char *key)
 Unsets a result's value, effectively removing the entry.
fx_module * fx_copy_module (fx_module *mod, const char *src_key, const char *dest_format,...)
 Copies a (sub)module, its contents, and documentation to a new location.
void fx_default_param (fx_module *mod, const char *key, const char *def_format,...)
 Defaults a parameter to a string formatted as in printf.
void fx_default_param_list (fx_module *mod, const char *key, size_t *size_ptr, size_t def_size,...)
 Defaults a parameter to a list of strings formatted as in printf.
void fx_done (fx_module *root)
 Finalizes, emits, and destructs an fx_module.
void fx_format_param (fx_module *mod, const char *key, const char *format,...)
 Sets a reserved parameter to a string formatted as in printf.
void fx_format_param_list (fx_module *mod, const char *key, size_t size,...)
 Sets a reserved parameter to a list of strings formatted as in printf.
void fx_format_result (fx_module *mod, const char *key, const char *format,...)
 Sets a result to a string formatted as in printf.
void fx_format_result_list (fx_module *mod, const char *key, size_t size,...)
 Sets a result to a list of strings formatted as in printf.
int fx_get_result_bool (fx_module *mod, const char *key)
 Obtains a boolean result, failing if not found.
int * fx_get_result_bool_list (fx_module *mod, const char *key, size_t *size_ptr)
 Obtains a list of boolean values from a result, failing if not found.
double fx_get_result_double (fx_module *mod, const char *key)
 Obtains a floating-point result, failing if not found.
double * fx_get_result_double_list (fx_module *mod, const char *key, size_t *size_ptr)
 Obtains a list of floating-point values from a result, failing if not found.
long long fx_get_result_int (fx_module *mod, const char *key)
 Obtains an integral result, failing if not found.
long long * fx_get_result_int_list (fx_module *mod, const char *key, size_t *size_ptr)
const char * fx_get_result_str (fx_module *mod, const char *key)
 Obtains a string result, failing if not found.
const char ** fx_get_result_str_list (fx_module *mod, const char *key, size_t *size_ptr)
 Obtains a list of strings from a result, failing if not found.
fx_timer * fx_get_timer (fx_module *mod, const char *key)
 Gets a timer for the purpose of reading its time.
success_t fx_help (const fx_module_doc *doc, const char *key)
 Prints help information from a FASTexec documentation structure for a given submodule.
fx_module * fx_init (int argc, char *argv[], const fx_module_doc *doc)
int fx_module_is_type (fx_module *entry, fx_mod_t mod_type)
 Tests whether an entry could be considered to be of a given type.
int fx_param_bool (fx_module *mod, const char *key, int def)
 Obtains a boolean parameter, using the provided default if unspecified.
int * fx_param_bool_array (fx_module *mod, const char *key, size_t *size_ptr, size_t def_size, const int *def_array)
 Obtains a list of comma-separated boolean values from a parameter, using the provided array as defaults if unspecified.
int * fx_param_bool_list (fx_module *mod, const char *key, size_t *size_ptr, size_t def_size,...)
 Obtains a list of comma-separated boolean values from a parameter, using the trailing arguments as defaults if unspecified.
int * fx_param_bool_list_req (fx_module *mod, const char *key, size_t *size_ptr)
 Obtains a list of boolean values from a parameter, failing if unspecified.
int fx_param_bool_req (fx_module *mod, const char *key)
 Obtains a boolean parameter, failing if unspecified.
double fx_param_double (fx_module *mod, const char *key, double def)
 Obtains a floating-point parameter, using the provided default if unspecified.
double * fx_param_double_array (fx_module *mod, const char *key, size_t *size_ptr, size_t def_size, const double *def_array)
 Obtains a list of comma-separated floating-point values from a parameter, using the provided array as defaults if unspecified.
double * fx_param_double_list (fx_module *mod, const char *key, size_t *size_ptr, size_t def_size,...)
 Obtains a list of comma-separated floating-point values from a parameter, using the trailing arguments as defaults if unspecified.
double * fx_param_double_list_req (fx_module *mod, const char *key, size_t *size_ptr)
 Obtains a list of floating-point values from a parameter, failing if unspecified.
double fx_param_double_req (fx_module *mod, const char *key)
 Obtains a floating-point parameter, failing if unspecified.
int fx_param_exists (fx_module *mod, const char *key)
 Tests whether a parameter has been specified.
long long fx_param_int (fx_module *mod, const char *key, long long def)
 Obtains an integral parameter, using the provided default if unspecified.
long long * fx_param_int_array (fx_module *mod, const char *key, size_t *size_ptr, size_t def_size, const long long *def_array)
 Obtains a list of comma-separated integral values from a parameter, using the provided array as defaults if unspecified.
long long * fx_param_int_list (fx_module *mod, const char *key, size_t *size_ptr, size_t def_size,...)
 Obtains a list of comma-separated integral values from a parameter, using the trailing arguments as defaults if unspecified.
long long * fx_param_int_list_req (fx_module *mod, const char *key, size_t *size_ptr)
long long fx_param_int_req (fx_module *mod, const char *key)
 Obtains an integral parameter, failing if unspecified.
const char * fx_param_str (fx_module *mod, const char *key, const char *def)
 Obtains a string parameter, using the provided default if unspecified.
const char ** fx_param_str_array (fx_module *mod, const char *key, size_t *size_ptr, size_t def_size, const char *const *def_array)
 Obtains a list of comma-separated strings from a parameter, using the provided array as defaults if unspecified.
const char ** fx_param_str_list (fx_module *mod, const char *key, size_t *size_ptr, size_t def_size,...)
 Obtains a list of comma-separated strings from a parameter, using the trailing arguments as defaults if unspecified.
const char ** fx_param_str_list_req (fx_module *mod, const char *key, size_t *size_ptr)
 Obtains a list of strings from a parameter, failing if unspecified.
const char * fx_param_str_req (fx_module *mod, const char *key)
 Obtains a string parameter, failing if unspecified.
void fx_reset_timer (fx_module *mod, const char *key)
 Resets a named timer's total time to zero.
void fx_result_bool (fx_module *mod, const char *key, int val)
 Sets a result to a given bool.
void fx_result_bool_array (fx_module *mod, const char *key, size_t size, const int *array)
 Sets a result to a given array of bools.
void fx_result_bool_list (fx_module *mod, const char *key, size_t size,...)
 Sets a result to a given list of bools.
void fx_result_double (fx_module *mod, const char *key, double val)
 Sets a result to a given double.
void fx_result_double_array (fx_module *mod, const char *key, size_t size, const double *array)
 Sets a result to a given array of doubles.
void fx_result_double_list (fx_module *mod, const char *key, size_t size,...)
 Sets a result to a given list of doubles.
int fx_result_exists (fx_module *mod, const char *key)
 Tests whether a result has been specified.
void fx_result_int (fx_module *mod, const char *key, long long val)
 Sets a result to a given int.
void fx_result_int_array (fx_module *mod, const char *key, size_t size, const long long *array)
 Sets a result to a given array of ints.
void fx_result_int_list (fx_module *mod, const char *key, size_t size,...)
 Sets a result to a given list of ints.
void fx_result_str (fx_module *mod, const char *key, const char *val)
 Sets a result to a given string.
void fx_result_str_array (fx_module *mod, const char *key, size_t size, const char *const *array)
 Sets a result to a given array of strings.
void fx_result_str_list (fx_module *mod, const char *key, size_t size,...)
 Sets a result to a given list of strings.
void fx_set_param_bool (fx_module *mod, const char *key, int val)
 Sets a reserved parameter to a given bool.
void fx_set_param_bool_array (fx_module *mod, const char *key, size_t size, const int *array)
 Sets a reserved parameter to a given array of booleans.
void fx_set_param_bool_list (fx_module *mod, const char *key, size_t size,...)
 Sets a reserved parameter to a given list of bools.
void fx_set_param_double (fx_module *mod, const char *key, double val)
 Sets a reserved parameter to a given double.
void fx_set_param_double_array (fx_module *mod, const char *key, size_t size, const double *array)
 Sets a reserved parameter to a given array of doubles.
void fx_set_param_double_list (fx_module *mod, const char *key, size_t size,...)
 Sets a reserved parameter to a given list of doubles.
void fx_set_param_int (fx_module *mod, const char *key, long long val)
 Sets a reserved parameter to a given int.
void fx_set_param_int_array (fx_module *mod, const char *key, size_t size, const long long *array)
 Sets a reserved parameter to a given array of ints.
void fx_set_param_int_list (fx_module *mod, const char *key, size_t size,...)
 Sets a reserved parameter to a given list of ints.
void fx_set_param_str (fx_module *mod, const char *key, const char *val)
 Sets a reserved parameter to a given string.
void fx_set_param_str_array (fx_module *mod, const char *key, size_t size, const char *const *array)
 Sets a reserved parameter to a given array of strings.
void fx_set_param_str_list (fx_module *mod, const char *key, size_t size,...)
 Sets a reserved parameter to a given list of strings.
fx_module * fx_submodule (fx_module *mod, const char *key)
 Paths into a submodule of a FASTexec module, permitting access of contained parameters without explicitly pathing to them.
void fx_timer_start (fx_module *mod, const char *key)
 Starts or continues a named timer, or creates one if it does not exist.
void fx_timer_stop (fx_module *mod, const char *key)
 Pauses a named timer.

Variables

const fx_module_doc fx__debug_doc
const fx_entry_doc fx__debug_entries []
const fx_module_doc fx__fx_doc
const fx_entry_doc fx__fx_entries []
const fx_module_doc fx__info_doc
const fx_entry_doc fx__info_entries []
const fx_submodule_doc fx__info_submods []
const fx_module_doc fx__rusage_doc
const fx_entry_doc fx__rusage_entries []
const fx_module_doc fx__std_doc
const fx_entry_doc fx__std_entries []
const fx_submodule_doc fx__std_submods []
const fx_module_doc fx__timer_doc
const fx_entry_doc fx__timer_entries []
int fx_docs_nagging = 1
 Whether to print messages about missing documentation.
char fx_mod_marker [] = "UMPQVPDRT"
 Markers for fx_mod_t values: UMPQVPDTR.
const char * fx_mod_name []
 Human-readable names for fx_mod_t values.
fx_module * fx_root = NULL
 The datanode under which all fx information is stored.
const char * fx_val_name []
 Human-readable names for fx_val_t values.

Detailed Description

Definitions for integration with the experiment-running system.

Definition in file fx.c.

Define Documentation

#define FX__FATAL ( prefix,
entry,
msg_params...   ) 
Value:
fx__print_fatal_msg(__FILE__, __FUNCTION__, __LINE__, \
        prefix, entry, msg_params)

Definition at line 311 of file fx.c.

#define FX__NONFATAL ( prefix,
entry,
msg_params...   ) 
Value:
fx__print_msg(__FILE__, __FUNCTION__, __LINE__, \
        FL_MSG_NONFATAL, prefix, entry, msg_params)

Definition at line 315 of file fx.c.

#define FX__SEMIFATAL ( success,
prefix,
entry,
msg_params...   ) 
Value:
if (!success) { \
      FX__FATAL(prefix, entry, msg_params); \
    } else if (!FAILED(*success)) { \
      *success = SUCCESS_FAIL; \
      FX__NONFATAL(prefix, entry, msg_params); \
    } else NOP

Definition at line 319 of file fx.c.

Function Documentation

void fx_clear_param ( fx_module *  mod,
const char *  key 
)

Unsets a parameter's value, effectively removing the entry.

Parameters:
mod the parameter's containing module
key the name of the parameter; paths allowed
fx_param_exists,fx_param_str 

Definition at line 1291 of file fx.c.

void fx_clear_result ( fx_module *  mod,
const char *  key 
)

Unsets a result's value, effectively removing the entry.

Parameters:
mod the result's containing module
key the name of the result; paths allowed
fx_result_exists,fx_param_exists,fx_result_str 

Definition at line 1532 of file fx.c.

fx_module* fx_copy_module ( fx_module *  mod,
const char *  src_key,
const char *  dest_format,
  ... 
)

Copies a (sub)module, its contents, and documentation to a new location.

This function is primarily useful when iterative steps of an algorithm deserve their own submodules for parameters and results.

Example (hypothetical manifold method's iteration): 

   fx_param_int(manifold_mod, "knn_i/leaf_size", 5);
   while (...) {
     fx_module *knn_i =
         fx_copy_module(manifold_mod, "knn_i", "knn_%d", iter);
     fx_set_param_int(knn_i, "k", cur_k);
     ...
     AllKNN allknn;
     allknn.Init(knn_i);
     ...
   }

This code first provides an alternate default for parameter "leaf_size" of knn_i, which may have been specified on the command line and is presumably different from the default that class AllKNN uses. It then copies the submodule (replicating any command line arguments and the default for "leaf_size") for each iteration of a loop, setting a specific value for "k".

Example (forwarding documentation): 

   while(...) {
     fx_module *timer_mod =
         fx_copy_module(manifold_mod, "time_i", "time_%d", iter);
     ...
     fx_timer_start(timer_mod, ".");
     ...
   }

FASTexec is rather pedantic about documentation, but tricks like the above allow you to have run-time generated entries that borrow documentation from entries specified in the fx_entry_docs. Also, the printf-like formatting of destination names makes it easier for you to give your generated entries unique names.

Parameters:
mod the containing module of the source and destination
src_key the name of the source submodule; paths allowed
dest_format a format string for the destination name
... format arguments, as in printf
Returns:
the dest fx_module * (struct datanode *); do not free
See also:
fx_submodule, fx_param_str, fx_init, fx_done

Definition at line 1597 of file fx.c.

References datanode_copy(), fx_module_is_type(), and datanode::mod_type.

Referenced by GeneralCrossValidator< TLearner >::Run(), and SimpleCrossValidator< TClassifier >::Run().

void fx_default_param ( fx_module *  mod,
const char *  key,
const char *  def_format,
  ... 
)

Defaults a parameter to a string formatted as in printf.

See also:
fx_param_str, fx_default_param_list, fx_format_param

Definition at line 1237 of file fx.c.

Referenced by DoSvmNormalize().

void fx_default_param_list ( fx_module *  mod,
const char *  key,
size_t *  size_ptr,
size_t  def_size,
  ... 
)

Defaults a parameter to a list of strings formatted as in printf.

Values should be provided in batches composed of element format strings followed by their arguments.

Example (the cheese stands alone): 

   fx_default_param_list(root, "foo", 3,
       "%s chases %s", dog_name, cat_name,
       "%d mice observed", mouse_count,
       "%g%% cheese remaining", 100 * cheese);
See also:
fx_param_str_list, fx_default_param, fx_format_param_list

Definition at line 1251 of file fx.c.

void fx_done ( fx_module *  root  ) 

Finalizes, emits, and destructs an fx_module.

You should always use fx_init to create fx_modules and fx_done when finished with them.

Parameter settings, measured times, and results are printed to screen unless boolean fx/silent has been set (from the command line or otherwise). This information is also written to the file given by string fx/store, if provided.

You may also optionally emit rusage information by setting boolean fx/rusage.

See also:
fx_param_init

Definition at line 2071 of file fx.c.

References datanode_destroy(), fx_param_bool(), fx_root, fx_submodule(), and timestamp_now().

Referenced by main().

void fx_format_param ( fx_module *  mod,
const char *  key,
const char *  format,
  ... 
)

Sets a reserved parameter to a string formatted as in printf.

See also:
fx_set_param_str, fx_default_param, fx_format_param_list

Definition at line 1265 of file fx.c.

void fx_format_param_list ( fx_module *  mod,
const char *  key,
size_t  size,
  ... 
)

Sets a reserved parameter to a list of strings formatted as in printf.

Values should be provided in batches composed of element format strings followed by their arguments.

See also:
fx_set_param_str_list, fx_default_param_list, fx_format_param

Definition at line 1277 of file fx.c.

void fx_format_result ( fx_module *  mod,
const char *  key,
const char *  format,
  ... 
)

Sets a result to a string formatted as in printf.

See also:
fx_result_str, fx_format_result_list, fx_format_param

Definition at line 1506 of file fx.c.

Referenced by NaiveKde< TKernel >::ComputeMaximumRelativeError(), main(), GeneralCrossValidator< TLearner >::Run(), and SimpleCrossValidator< TClassifier >::Run().

void fx_format_result_list ( fx_module *  mod,
const char *  key,
size_t  size,
  ... 
)

Sets a result to a list of strings formatted as in printf.

Values should be provided in batches composed of element format strings followed by their arguments.

See also:
fx_result_str_list, fx_format_result, fx_format_param_list

Definition at line 1518 of file fx.c.

int fx_get_result_bool ( fx_module *  mod,
const char *  key 
)

Obtains a boolean result, failing if not found.

Parameters:
mod the result's containing module
key the name of the result; paths allowed
Returns:
an int with value 1 or 0
See also:
fx_result_bool, fx_get_result_bool_list, fx_param_bool

Definition at line 1347 of file fx.c.

int* fx_get_result_bool_list ( fx_module *  mod,
const char *  key,
size_t *  size_ptr 
)

Obtains a list of boolean values from a result, failing if not found.

See also:
fx_get_result_bool, fx_result_bool_list, fx_param_bool_list

Definition at line 1375 of file fx.c.

double fx_get_result_double ( fx_module *  mod,
const char *  key 
)

Obtains a floating-point result, failing if not found.

Parameters:
mod the result's containing module
key the name of the result; paths allowed
Returns:
a double
See also:
fx_result_double, fx_get_result_double_list, fx_param_double

Definition at line 1337 of file fx.c.

double* fx_get_result_double_list ( fx_module *  mod,
const char *  key,
size_t *  size_ptr 
)

Obtains a list of floating-point values from a result, failing if not found.

See also:
fx_get_result_double, fx_result_double_list, fx_param_double_list

Definition at line 1361 of file fx.c.

long long fx_get_result_int ( fx_module *  mod,
const char *  key 
)

Obtains an integral result, failing if not found.

Parameters:
mod the result's containing module
key the name of the result; paths allowed
Returns:
a long long; type may be converted implicitly
See also:
fx_result_int, fx_get_result_int_list, fx_param_int

Definition at line 1342 of file fx.c.

const char* fx_get_result_str ( fx_module *  mod,
const char *  key 
)

Obtains a string result, failing if not found.

Parameters:
mod the result's containing module
key the name of the result; paths allowed
Returns:
a const char *; do not free
See also:
fx_result_str, fx_get_result_str_list, fx_param_str

Definition at line 1332 of file fx.c.

const char** fx_get_result_str_list ( fx_module *  mod,
const char *  key,
size_t *  size_ptr 
)

Obtains a list of strings from a result, failing if not found.

See also:
fx_get_result_str, fx_result_str_list, fx_param_str_list

Definition at line 1354 of file fx.c.

fx_timer* fx_get_timer ( fx_module *  mod,
const char *  key 
)

Gets a timer for the purpose of reading its time.

Parameters:
mod the timer's containing module
key the name of the timer; paths allowed
Returns:
an fx_timer * (struct stopwatch *); do not free
See also:
struct stopwatch, fx_timer_start, fx_timer_stop

Definition at line 1553 of file fx.c.

References stopwatch_init().

Referenced by fx_reset_timer(), fx_timer_start(), fx_timer_stop(), and main().

success_t fx_help ( const fx_module_doc *  doc,
const char *  key 
)

Prints help information from a FASTexec documentation structure for a given submodule.

This function is somewhat distinct from other FASTexec routines because it works directly on the fx_module_doc structure rather than an fx_module. Pathing works similarly, though ".." does not work because documentation structures do not necessarily have unique parents. Use "" to obtain the structure's root details.

All possible matches to the queried key are printed to screen.

Parameters:
doc the documentation structure containing the submodule
key the name of the submodule; paths allowed
See also:
fx_module_doc, fx_init

Definition at line 1650 of file fx.c.

References fx_submodule_doc::doc, fx_module_doc::entries, fx_mod_name, fx_val_name, fx_submodule_doc::key, fx_entry_doc::key, fx_entry_doc::mod_type, fx_module_doc::submodules, fx_submodule_doc::text, fx_entry_doc::text, fx_module_doc::text, and fx_entry_doc::val_type.

int fx_module_is_type ( fx_module *  entry,
fx_mod_t  type 
)

Tests whether an entry could be considered to be of a given type.

Types have hierarchical relationships given as follows: 

   FX_UNKNOWN
     FX_MODULE
       FX_PARAM
         FX_REQUIRED
           FX_RESERVED
           FX_PROVIDED
           FX_DEFAULT
       FX_TIMER
       FX_RESULT

Thus, FX_REQUIRED may also serve as FX_PARAM, but not the other way around; additionally FX_RESERVED, FX_PROVIDED, and FX_DEFAULT satisfy FX_REQUIRED. Note that any kind of entry other than an FX_UNKNOWN may serve as an FX_MODULE, meaning that every kind of entry is permitted to have child entries and, equivalently, that it is possible for entries with children (modules) to have values.

Parameters:
entry the entry to be tested
type the type to look for, i.e. is mod of this type?
See also:
fx_mod_t, struct fx_module

Definition at line 329 of file fx.c.

Referenced by fx_copy_module().

int fx_param_bool ( fx_module *  mod,
const char *  key,
int  def 
)

Obtains a boolean parameter, using the provided default if unspecified.

Booleans should be given with leading character in either set "1tTyY" for true or "0fFnN" for false. The empty string is also considered true, and thus booleans set on the command line with "--some/bool" (omitting the '=t') are true.

Parameters:
mod the parameter's containing module
key the name of the parameter; paths allowed
def value used if parameter not given
Returns:
an int with value 1 or 0
See also:
fx_param_str, fx_param_bool_list, fx_param_bool_req fx_set_param_bool

Definition at line 980 of file fx.c.

Referenced by DoSvmNormalize(), fx_done(), FastICA::Init(), LoadData(), GeneralCrossValidator< TLearner >::Run(), and SimpleCrossValidator< TClassifier >::Run().

int* fx_param_bool_array ( fx_module *  mod,
const char *  key,
size_t *  size_ptr,
size_t  def_size,
const int *  def_array 
)

Obtains a list of comma-separated boolean values from a parameter, using the provided array as defaults if unspecified.

See also:
fx_param_bool_list

Definition at line 1100 of file fx.c.

int* fx_param_bool_list ( fx_module *  mod,
const char *  key,
size_t *  size_ptr,
size_t  def_size,
  ... 
)

Obtains a list of comma-separated boolean values from a parameter, using the trailing arguments as defaults if unspecified.

Input *size_ptr must be initialized. If nonzero, it establishes a required list length. For example, you may set *size_ptr = 0 but then use it for multiple lists to ensure they are the same length.

Do not free the returned list.

Parameters:
mod the parameter's containing module
key the name of the parameter; paths allowed
size_ptr receives the length of the list or establishes the required length of the list if nonzero
def_size the number of trailing arguments
... values to be used if parameter not given
Returns:
an int * with values 1 or 0; do not free
See also:
fx_param_str_list, fx_param_bool, fx_param_bool_array, fx_param_bool_list_req, fx_set_param_bool_list

Definition at line 1043 of file fx.c.

int* fx_param_bool_list_req ( fx_module *  mod,
const char *  key,
size_t *  size_ptr 
)

Obtains a list of boolean values from a parameter, failing if unspecified.

See also:
fx_param_int_list

Definition at line 934 of file fx.c.

int fx_param_bool_req ( fx_module *  mod,
const char *  key 
)

Obtains a boolean parameter, failing if unspecified.

See also:
fx_param_bool

Definition at line 906 of file fx.c.

double fx_param_double ( fx_module *  mod,
const char *  key,
double  def 
)

Obtains a floating-point parameter, using the provided default if unspecified.

Parameters:
mod the parameter's containing module
key the name of the parameter; paths allowed
def value used if parameter not given
Returns:
a double
See also:
fx_param_str, fx_param_double_list, fx_param_double_req, fx_set_param_double

Definition at line 954 of file fx.c.

Referenced by NaiveKde< TKernel >::ComputeMaximumRelativeError(), GenerateArtificialDataset(), SVM< TKernel >::Init(), FastICA::Init(), and main().

double* fx_param_double_array ( fx_module *  mod,
const char *  key,
size_t *  size_ptr,
size_t  def_size,
const double *  def_array 
)

Obtains a list of comma-separated floating-point values from a parameter, using the provided array as defaults if unspecified.

See also:
fx_param_double_list

Definition at line 1074 of file fx.c.

double* fx_param_double_list ( fx_module *  mod,
const char *  key,
size_t *  size_ptr,
size_t  def_size,
  ... 
)

Obtains a list of comma-separated floating-point values from a parameter, using the trailing arguments as defaults if unspecified.

Input *size_ptr must be initialized. If nonzero, it establishes a required list length. For example, you may set *size_ptr = 0 but then use it for multiple lists to ensure they are the same length.

Do not free the returned list.

Parameters:
mod the parameter's containing module
key the name of the parameter; paths allowed
size_ptr receives the length of the list or establishes the required length of the list if nonzero
def_size the number of trailing arguments
... values to be used if parameter not given
Returns:
a double *; do not free
See also:
fx_param_str_list, fx_param_double, fx_param_double_array, fx_param_double_list_req, fx_set_param_double_list

Definition at line 1011 of file fx.c.

double* fx_param_double_list_req ( fx_module *  mod,
const char *  key,
size_t *  size_ptr 
)

Obtains a list of floating-point values from a parameter, failing if unspecified.

See also:
fx_param_double_list

Definition at line 920 of file fx.c.

double fx_param_double_req ( fx_module *  mod,
const char *  key 
)

Obtains a floating-point parameter, failing if unspecified.

See also:
fx_param_double

Definition at line 896 of file fx.c.

Referenced by NaiveKde< TKernel >::Init(), and FFTKde::Init().

int fx_param_exists ( fx_module *  mod,
const char *  key 
)

Tests whether a parameter has been specified.

Parameters:
mod the parameter's containing module
key the name of the parameter; paths allowed
Returns:
whether the parameter has a value
See also:
fx_param_clear, fx_param_str

Definition at line 1301 of file fx.c.

Referenced by LoadData(), and main().

long long fx_param_int ( fx_module *  mod,
const char *  key,
long long  def 
)

Obtains an integral parameter, using the provided default if unspecified.

Parameters:
mod the parameter's containing module
key the name of the parameter; paths allowed
def value used if parameter not given
Returns:
a long long; type may be converted implicitly
See also:
fx_param_str, fx_param_int_list, fx_param_int_req fx_set_param_int

Definition at line 967 of file fx.c.

Referenced by GenerateArtificialDataset(), SVM< TKernel >::Init(), OrthoRangeSearch< T >::Init(), FFTKde::Init(), FastICA::Init(), DiskAllNN::Init(), AllkNN::Init(), AllkFN::Init(), GeneralCrossValidator< TLearner >::Init(), SimpleCrossValidator< TClassifier >::Init(), AllNN::Init(), and tree::LoadKdTree().

long long* fx_param_int_array ( fx_module *  mod,
const char *  key,
size_t *  size_ptr,
size_t  def_size,
const long long *  def_array 
)

Obtains a list of comma-separated integral values from a parameter, using the provided array as defaults if unspecified.

See also:
fx_param_int_list

Definition at line 1087 of file fx.c.

long long* fx_param_int_list ( fx_module *  mod,
const char *  key,
size_t *  size_ptr,
size_t  def_size,
  ... 
)

Obtains a list of comma-separated integral values from a parameter, using the trailing arguments as defaults if unspecified.

Input *size_ptr must be initialized. If nonzero, it establishes a required list length. For example, you may set *size_ptr = 0 but then use it for multiple lists to ensure they are the same length.

Do not free the returned list.

Parameters:
mod the parameter's containing module
key the name of the parameter; paths allowed
size_ptr receives the length of the list or establishes the required length of the list if nonzero
def_size the number of trailing arguments
... values to be used if parameter not given
Returns:
a long long *; no implicit type conversion; do not free
See also:
fx_param_str_list, fx_param_int, fx_param_int_array, fx_param_int_list_req, fx_set_param_int_list

Definition at line 1027 of file fx.c.

long long fx_param_int_req ( fx_module *  mod,
const char *  key 
)

Obtains an integral parameter, failing if unspecified.

See also:
fx_param_int

Definition at line 901 of file fx.c.

Referenced by NaiveKde< TKernel >::Init(), SimpleNaiveBayesClassifier::InitTrain(), and main().

const char* fx_param_str ( fx_module *  mod,
const char *  key,
const char *  def 
)

Obtains a string parameter, using the provided default if unspecified.

Parameters:
mod the parameter's containing module
key the name of the parameter; paths allowed
def value used if parameter not given
Returns:
a const char *; do not free
See also:
fx_param_double, fx_param_int, fx_param_bool, fx_param_str_list, fx_param_str_req, fx_set_param_str, fx_default_param

Definition at line 943 of file fx.c.

Referenced by NaiveKde< TKernel >::Init(), FastICA::Init(), DiskAllNN::Init(), AllkNN::Init(), tree::LoadKdTree(), main(), NaiveKde< TKernel >::PrintDebug(), and FFTKde::PrintDebug().

const char** fx_param_str_array ( fx_module *  mod,
const char *  key,
size_t *  size_ptr,
size_t  def_size,
const char *const *  def_array 
)

Obtains a list of comma-separated strings from a parameter, using the provided array as defaults if unspecified.

See also:
fx_param_str_list

Definition at line 1061 of file fx.c.

const char** fx_param_str_list ( fx_module *  mod,
const char *  key,
size_t *  size_ptr,
size_t  def_size,
  ... 
)

Obtains a list of comma-separated strings from a parameter, using the trailing arguments as defaults if unspecified.

Element strings may contain escaped commas given by "%2c". Because '' is itself be escaped, this is "%252c" from the command line.

Input *size_ptr must be initialized. If nonzero, it establishes a required list length. For example, you may set *size_ptr = 0 but then use it for multiple lists to ensure they are the same length.

Do not free the returned list.

Parameters:
mod the parameter's containing module
key the name of the parameter; paths allowed
size_ptr receives the length of the list or establishes the required length of the list if nonzero
def_size the number of trailing arguments
... values to be used if parameter not given
Returns:
a const char **; do not free
See also:
fx_param_double_list, fx_param_int_list, fx_param_bool_list, fx_param_str, fx_param_str_array, fx_param_str_list_req, fx_set_param_str_list, fx_default_param_list

Definition at line 995 of file fx.c.

const char** fx_param_str_list_req ( fx_module *  mod,
const char *  key,
size_t *  size_ptr 
)

Obtains a list of strings from a parameter, failing if unspecified.

See also:
fx_param_str_list

Definition at line 913 of file fx.c.

const char* fx_param_str_req ( fx_module *  mod,
const char *  key 
)

Obtains a string parameter, failing if unspecified.

See also:
fx_param_str

Definition at line 891 of file fx.c.

Referenced by LoadData(), and main().

void fx_reset_timer ( fx_module *  mod,
const char *  key 
)

Resets a named timer's total time to zero.

Parameters:
mod the timer's containing module
key the name of the timer; paths allowed
See also:
fx_timer_start, fx_timer_stop, fx_get_timer

Definition at line 1581 of file fx.c.

References fx_get_timer(), and stopwatch_init().

void fx_result_bool ( fx_module *  mod,
const char *  key,
int  val 
)

Sets a result to a given bool.

See also:
fx_result_str, fx_result_bool_list, fx_get_result_bool, fx_param_bool

Definition at line 1408 of file fx.c.

void fx_result_bool_array ( fx_module *  mod,
const char *  key,
size_t  size,
const int *  array 
)

Sets a result to a given array of bools.

See also:
fx_result_bool_list, fx_param_bool_list

Definition at line 1495 of file fx.c.

void fx_result_bool_list ( fx_module *  mod,
const char *  key,
size_t  size,
  ... 
)

Sets a result to a given list of bools.

See also:
fx_get_result_bool_list, fx_result_bool, fx_result_bool_array, fx_param_bool_list

Definition at line 1454 of file fx.c.

void fx_result_double ( fx_module *  mod,
const char *  key,
double  val 
)

Sets a result to a given double.

See also:
fx_result_str, fx_result_double_list, fx_get_result_double, fx_param_double

Definition at line 1392 of file fx.c.

void fx_result_double_array ( fx_module *  mod,
const char *  key,
size_t  size,
const double *  array 
)

Sets a result to a given array of doubles.

See also:
fx_result_double_list, fx_param_double_list

Definition at line 1477 of file fx.c.

void fx_result_double_list ( fx_module *  mod,
const char *  key,
size_t  size,
  ... 
)

Sets a result to a given list of doubles.

See also:
fx_get_result_double_list, fx_result_double, fx_result_double_array, fx_param_double_list

Definition at line 1430 of file fx.c.

int fx_result_exists ( fx_module *  mod,
const char *  key 
)

Tests whether a result has been specified.

Parameters:
mod the result's containing module
key the name of the result; paths allowed
Returns:
whether the result has a value
See also:
fx_result_clear, fx_param_clear, fx_result_str

Definition at line 1542 of file fx.c.

void fx_result_int ( fx_module *  mod,
const char *  key,
long long  val 
)

Sets a result to a given int.

See also:
fx_result_str, fx_result_int_list, fx_get_result_int, fx_param_int

Definition at line 1400 of file fx.c.

Referenced by SimpleNaiveBayesClassifier::Classify(), DiskAllNN::ComputeNeighbors(), AllNN::ComputeNeighbors(), and SimpleNaiveBayesClassifier::InitTrain().

void fx_result_int_array ( fx_module *  mod,
const char *  key,
size_t  size,
const long long *  array 
)

Sets a result to a given array of ints.

See also:
fx_result_int_list, fx_param_int_list

Definition at line 1486 of file fx.c.

void fx_result_int_list ( fx_module *  mod,
const char *  key,
size_t  size,
  ... 
)

Sets a result to a given list of ints.

See also:
fx_get_result_int_list, fx_result_int, fx_result_int_array, fx_param_int_list

Definition at line 1442 of file fx.c.

void fx_result_str ( fx_module *  mod,
const char *  key,
const char *  val 
)

Sets a result to a given string.

See also:
fx_result_dobule, fx_result_int, fx_result_bool, fx_result_str_list, fx_get_result_str, fx_param_str, fx_format_result

Definition at line 1384 of file fx.c.

void fx_result_str_array ( fx_module *  mod,
const char *  key,
size_t  size,
const char *const *  array 
)

Sets a result to a given array of strings.

See also:
fx_result_str_list, fx_param_str_list

Definition at line 1468 of file fx.c.

void fx_result_str_list ( fx_module *  mod,
const char *  key,
size_t  size,
  ... 
)

Sets a result to a given list of strings.

See also:
fx_get_result_str_list, fx_result_str, fx_result_str_array, fx_param_str_list, fx_format_result_list

Definition at line 1418 of file fx.c.

void fx_set_param_bool ( fx_module *  mod,
const char *  key,
int  val 
)

Sets a reserved parameter to a given bool.

See also:
fx_param_bool, fx_set_param_bool_list, fx_result_bool

Definition at line 1139 of file fx.c.

void fx_set_param_bool_array ( fx_module *  mod,
const char *  key,
size_t  size,
const int *  array 
)

Sets a reserved parameter to a given array of booleans.

See also:
fx_param_bool_array, fx_set_param_bool_list

Definition at line 1226 of file fx.c.

void fx_set_param_bool_list ( fx_module *  mod,
const char *  key,
size_t  size,
  ... 
)

Sets a reserved parameter to a given list of bools.

See also:
fx_param_bool_list, fx_set_param_bool, fx_set_param_bool_array, fx_result_bool_list

Definition at line 1185 of file fx.c.

void fx_set_param_double ( fx_module *  mod,
const char *  key,
double  val 
)

Sets a reserved parameter to a given double.

See also:
fx_param_double, fx_set_param_double_list, fx_result_double

Definition at line 1123 of file fx.c.

void fx_set_param_double_array ( fx_module *  mod,
const char *  key,
size_t  size,
const double *  array 
)

Sets a reserved parameter to a given array of doubles.

See also:
fx_param_double_array, fx_set_param_double_list

Definition at line 1208 of file fx.c.

void fx_set_param_double_list ( fx_module *  mod,
const char *  key,
size_t  size,
  ... 
)

Sets a reserved parameter to a given list of doubles.

See also:
fx_param_double_list, fx_set_param_double, fx_set_param_double_array, fx_result_double_list

Definition at line 1161 of file fx.c.

void fx_set_param_int ( fx_module *  mod,
const char *  key,
long long  val 
)

Sets a reserved parameter to a given int.

See also:
fx_param_int, fx_set_param_int_list, fx_result_int

Definition at line 1131 of file fx.c.

void fx_set_param_int_array ( fx_module *  mod,
const char *  key,
size_t  size,
const long long *  array 
)

Sets a reserved parameter to a given array of ints.

See also:
fx_param_int_array, fx_set_param_int_list

Definition at line 1217 of file fx.c.

void fx_set_param_int_list ( fx_module *  mod,
const char *  key,
size_t  size,
  ... 
)

Sets a reserved parameter to a given list of ints.

See also:
fx_param_int_list, fx_set_param_int, fx_set_param_int_array, fx_result_int_list

Definition at line 1173 of file fx.c.

void fx_set_param_str ( fx_module *  mod,
const char *  key,
const char *  val 
)

Sets a reserved parameter to a given string.

See also:
fx_param_str, fx_set_param_str_list, fx_result_str, fx_format_param

Definition at line 1115 of file fx.c.

void fx_set_param_str_array ( fx_module *  mod,
const char *  key,
size_t  size,
const char *const *  array 
)

Sets a reserved parameter to a given array of strings.

See also:
fx_param_str_array, fx_set_param_str_list

Definition at line 1199 of file fx.c.

void fx_set_param_str_list ( fx_module *  mod,
const char *  key,
size_t  size,
  ... 
)

Sets a reserved parameter to a given list of strings.

See also:
fx_param_str_list, fx_set_param_str, fx_set_param_str_array, fx_result_str_list, fx_format_param_list

Definition at line 1149 of file fx.c.

fx_module* fx_submodule ( fx_module *  mod,
const char *  key 
)

Paths into a submodule of a FASTexec module, permitting access of contained parameters without explicitly pathing to them.

If the submodule does not exist, it is created and is initialy empty. Parameter access will then populate it with defaults.

Submodules serve to compartmentalize modular components of a program, e.g. so that their parameters and results may be managed separately from those of other components. Working within a submodule should be understood as changing the working directory in a UNIX file system. Like the terms "directory" and "subdirectory", there is no real distinction between "module" and "submodule" except relative to one another.

Example (tree building command line input): 

   ./myprog --r=data.txt --r/leaf_size=30 --r/split_median

Example (tree building parameter parsing): 

   const char *r_file = fx_param_str_req(root, "r")
   ...
   fx_module *r_mod = fx_submodule(root, "r");
   int leaf_size = fx_param_int(r_mod, "leaf_size", 30);
   int split_median = fx_param_bool(r_mod, "split_median", 0);

Note that submodules may also have values. It is possible to obtain the value of "r" from r_mod with fx_param_str(r_mod, ".")

Parameters:
mod the containing module of the submodule
key the name of the submodule; paths allowed
Returns:
an fx_module * (struct datanode *); do not free
See also:
fx_copy_module, fx_param_str, fx_init, fx_done

Definition at line 1588 of file fx.c.

Referenced by fx_done(), SVM< TKernel >::Init(), GeneralCrossValidator< TLearner >::Init(), SimpleCrossValidator< TClassifier >::Init(), main(), GeneralCrossValidator< TLearner >::Run(), and SimpleCrossValidator< TClassifier >::Run().

void fx_timer_start ( fx_module *  mod,
const char *  key 
)

Starts or continues a named timer, or creates one if it does not exist.

Parameters:
mod the timer's containing module
key the name of the timer; paths allowed
See also:
fx_timer_stop, fx_reset_timer, fx_get_timer

Definition at line 1568 of file fx.c.

References fx_get_timer(), and stopwatch_start().

Referenced by OrthoRangeSearch< T >::Compute(), NaiveOrthoRangeSearch< T >::Compute(), NaiveKde< TKernel >::Compute(), FFTKde::Compute(), DiskAllNN::ComputeNaive(), AllNN::ComputeNaive(), DiskAllNN::ComputeNeighbors(), AllkNN::ComputeNeighbors(), AllNN::ComputeNeighbors(), OrthoRangeSearch< T >::Init(), NaiveKde< TKernel >::Init(), FFTKde::Init(), DiskAllNN::Init(), AllkNN::Init(), AllkFN::Init(), AllNN::Init(), tree::LoadKdTree(), GeneralCrossValidator< TLearner >::Run(), and SimpleCrossValidator< TClassifier >::Run().

void fx_timer_stop ( fx_module *  mod,
const char *  key 
)

Pauses a named timer.

Parameters:
mod the timer's containing module
key the name of the timer; paths allowed
See also:
fx_timer_start, fx_reset_timer, fx_get_timer

Definition at line 1573 of file fx.c.

References fx_get_timer(), stopwatch_stop(), and timestamp_now().

Referenced by OrthoRangeSearch< T >::Compute(), NaiveOrthoRangeSearch< T >::Compute(), NaiveKde< TKernel >::Compute(), FFTKde::Compute(), DiskAllNN::ComputeNaive(), AllNN::ComputeNaive(), DiskAllNN::ComputeNeighbors(), AllkNN::ComputeNeighbors(), AllNN::ComputeNeighbors(), OrthoRangeSearch< T >::Init(), NaiveKde< TKernel >::Init(), FFTKde::Init(), DiskAllNN::Init(), AllkNN::Init(), AllkFN::Init(), AllNN::Init(), tree::LoadKdTree(), GeneralCrossValidator< TLearner >::Run(), and SimpleCrossValidator< TClassifier >::Run().

Variable Documentation

const fx_module_doc fx__debug_doc
Initial value:
 {
  fx__debug_entries, NULL,
  "Options for FASTlib's debugging features.\n"
}

Definition at line 136 of file fx.c.

const fx_entry_doc fx__debug_entries[]
Initial value:
 {
  {"verbosity_level", FX_PARAM, FX_DOUBLE, NULL,
   "  Controls the amount of debug info to print.\n"},
  {"print_got_heres", FX_PARAM, FX_BOOL, NULL,
   "  Whether to print \"got here\" notices.\n"},
  {"print_warnings", FX_PARAM, FX_BOOL, NULL,
   "  Whether to print warning messages.\n"},
  {"abort_on_nonfatal", FX_PARAM, FX_BOOL, NULL,
   "  Whether to treat nonfatal errors as fatal.\n"},
  {"pause_on_nonfatal", FX_PARAM, FX_BOOL, NULL,
   "  Whether to wait for user feedback on nonfatal errors.\n"},
  {"print_notify_locs", FX_PARAM, FX_BOOL, NULL,
   "  Whether to print \"file:function:line:\" before notifications.\n"},
  FX_ENTRY_DOC_DONE
}

Definition at line 120 of file fx.c.

const fx_module_doc fx__fx_doc
Initial value:
 {
  fx__fx_entries, NULL,
  "Options for the FASTexec experiment-running system.\n"
}

Definition at line 115 of file fx.c.

const fx_entry_doc fx__fx_entries[]
Initial value:
 {
  {"load", FX_PARAM, FX_STR_LIST, NULL,
   "  Load files containing additional input parameters.\n"},
  {"output", FX_PARAM, FX_STR, NULL,
   "  Output results to this file.\n"},
  {"timing", FX_PARAM, FX_BOOL, NULL,
   "  Whether to attempt speed up for a timing run.\n"},
  {"rusage", FX_PARAM, FX_BOOL, NULL,
   "  Whether to emit rusage data in \"info\".\n"},
  {"silent", FX_PARAM, FX_BOOL, NULL,
   "  Whether to skip the printing of results to screen.\n"},
  {"no_output_types", FX_PARAM, FX_BOOL, NULL,
   "  Whether to skip the printing of entry types (e.g. \"/param:P\").\n"},
  {"no_docs_nagging", FX_PARAM, FX_BOOL, NULL,
   "  Whether to suppress messages about missing documentation.\n"},
  FX_ENTRY_DOC_DONE
}

Definition at line 97 of file fx.c.

const fx_module_doc fx__info_doc
Initial value:
 {
  fx__info_entries, fx__info_submods,
  "Extraneous system details pertaining to an experiment.\n"
}

Definition at line 208 of file fx.c.

const fx_entry_doc fx__info_entries[]
Initial value:
 {
  {"sys/node/name", FX_RESULT, FX_STR, NULL,
   "  The host computer of the experiment.\n"},
  {"sys/arch/name", FX_RESULT, FX_STR, NULL,
   "  The host computer's architecture, i.e. 64-bit x86.\n"},
  {"sys/kernel/name", FX_RESULT, FX_STR, NULL,
   "  The name of operating system.\n"},
  {"sys/kernel/release", FX_RESULT, FX_STR, NULL,
   "  The version of the operating system.\n"},
  {"sys/kernel/build", FX_RESULT, FX_STR, NULL,
   "  Further OS version details.\n"},
  FX_ENTRY_DOC_DONE
}

Definition at line 194 of file fx.c.

const fx_submodule_doc fx__info_submods[]
Initial value:
 {
  {"rusage/self", &fx__rusage_doc,
   "  Resources consumed by the experiment's main thread.\n"},
  {"rusage/children", &fx__rusage_doc,
   "  Resources consumed by all child threads.\n"},
  FX_SUBMODULE_DOC_DONE
}

Definition at line 186 of file fx.c.

const fx_module_doc fx__rusage_doc
Initial value:
 {
  fx__rusage_entries, NULL,
  "Resource usage information generated by getrusage.\n"
}

Definition at line 181 of file fx.c.

const fx_module_doc fx__std_doc
Initial value:
 {
  fx__std_entries, fx__std_submods,
  "Standard FASTlib options:\n"
}

Definition at line 231 of file fx.c.

const fx_entry_doc fx__std_entries[]
Initial value:
 {
  {"help", FX_PARAM, FX_STR, NULL,
   "  Prints this information.  Permits --help=path/to/submod.\n"},
  {"total_time", FX_TIMER, FX_CUSTOM, NULL,
   "  The measured running time of the program.\n"},
  FX_ENTRY_DOC_DONE
}

Definition at line 223 of file fx.c.

const fx_submodule_doc fx__std_submods[]
Initial value:
 {
  {"fx", &fx__fx_doc,
   "  Options for the FASTexec experiment-running system.\n"},
  {"debug", &fx__debug_doc,
   "  Options for FASTlib's debugging feautres.\n"},
  {"info", &fx__info_doc,
   "  Extraneous system details pertaining to an experiment.\n"},
  FX_SUBMODULE_DOC_DONE
}

Definition at line 213 of file fx.c.

const fx_module_doc fx__timer_doc
Initial value:
 {
  fx__timer_entries, NULL, "text"
}

Definition at line 246 of file fx.c.

const fx_entry_doc fx__timer_entries[]
Initial value:
 {
  {"cycles", FX_TIMER, FX_INT, NULL, "text"},
  {"real", FX_TIMER, FX_DOUBLE, NULL, "text"},
  {"user", FX_TIMER, FX_DOUBLE, NULL, "text"},
  {"sys", FX_TIMER, FX_DOUBLE, NULL, "text"},
  FX_ENTRY_DOC_DONE
}

Definition at line 238 of file fx.c.

int fx_docs_nagging = 1

Whether to print messages about missing documentation.

Definition at line 56 of file fx.c.

char fx_mod_marker[] = "UMPQVPDRT"

Markers for fx_mod_t values: UMPQVPDTR.

Definition at line 60 of file fx.c.

const char* fx_mod_name[]
Initial value:
 {
  "unknown",
  "submodule",
  "parameter",
  "required parameter",
  "reserved parameter",
  "provided parameter",
  "default parameter",
  "result",
  "timer"
}

Human-readable names for fx_mod_t values.

Definition at line 62 of file fx.c.

Referenced by fx_help().

fx_module* fx_root = NULL

The datanode under which all fx information is stored.

Definition at line 55 of file fx.c.

Referenced by fx_done(), NaiveKde< TKernel >::Init(), and main().

const char* fx_val_name[]
Initial value:
 {
  "string",
  "double",
  "int",
  "bool",
  "string list",
  "double list",
  "int list",
  "bool list"
}

Human-readable names for fx_val_t values.

Definition at line 74 of file fx.c.

Referenced by fx_help().

Generated on Mon Jan 24 12:04:38 2011 for FASTlib by  doxygen 1.6.3