Parse and maintain options that alter the execution of PStack. More...

#include <pstack_options.hpp>

Inheritance diagram for pstack::pstack_options:

Collaboration diagram for pstack::pstack_options:

Classes
struct	options_data
	The full set of options information available to pstack::pstack_options. More...

Type Definitions
using	pid_list = std::set< psystem::process_id_t >
	The a container for list of user-supplied process IDs.

Option Observers
static bool	get_image_symbols () noexcept
	Should PStack search modules on disk for symbols rather than using built-in libraries? More...

static pid_list const &	process_id_list () noexcept
	Access the list of process IDs specified on the command-line. More...

static psystem::tstring const &	program_name () noexcept
	Access the name this program was invoked with. More...

static bool	search_all_threads () noexcept
	Should PStack output stack traces for all threads? More...

static bool	show_frames () noexcept
	Should PStack output frame pointers for each stack frame? More...

static bool	show_debug () noexcept
	Should the user output verbose debug information? More...

static bool	show_error () noexcept
	Should the user output errors in the flow of execution? More...

static bool	show_info () noexcept
	Should the user output extra informational messaging? More...

Informational Functions
static void	print_usage () noexcept
	Print command-line help information to the screen. More...

static void	print_version_info () noexcept
	Output information about the PStack's version to the screen. More...

static void	print_usage (const char *const prog_name) noexcept
	Print command-line help information to the screen. More...

Construction / Destruction
	pstack_options (int argc, char const *argv[])
	Construct the pstack_options instance. More...

	~pstack_options () noexcept
	Deallocate the options instance. More...

Private Utilities
static void	dump_arguments (pstack_options::options_data const &d) noexcept
	Output all the command-line data to `stdout`. More...

void	try_pid (char const *arg)
	Try to interpret a CLI parameter as a process ID. More...

void	try_switch (char arg)
	Try to alter the options data based on a single character CLI switch. More...

Member Data
std::unique_ptr< options_data >	m_data
	A pointer to the options data (PImpl pattern).

Additional Inherited Members
Private Member Functions inherited from psystem::not_copyable
	not_copyable (not_copyable const &)=delete
	Delete the copy constructor.

not_copyable &	operator= (not_copyable const &)=delete
	Delete the assignment operator.

constexpr	not_copyable () noexcept
	A simple CTOR suitable for noexcept and constexpr uses.

	~not_copyable () noexcept
	A simple CTOR suitable for noexcept uses.

Detailed Description

Parse and maintain options that alter the execution of PStack.

None of the "Option Observers" will function in this interface until one (and only one) instance of pstack_options has been instantiated. Only the main method is allowed to construct an instance of this class. This pstack_options is a singleton, and the lifetime is limited to a predictable scope in main.

Since this uses the PImpl pattern, we will make this class not_copyable, rather than redefining the copy constructor to do a deep copy of the "impl." Copying isn't useful at the moment anyway.

Author: Matt Bisson

Date: 25 November, 2007 – 5 August, 2014

Since: PStack 1.0

Version: PStack 2.0

Copyright: This file is distributed under the University of Illinois Open Source License. See LICENSE.TXT for details.

Constructor & Destructor Documentation

pstack::pstack_options::pstack_options	(	int	argc,
		char const *	argv[]
	)

private

Construct the pstack_options instance.

This method is private because it is only intended to be called from the main function (main is a friend of this class). This is because the constructor has a side-effect of populating a global (singleton) pointer with this. When main allocates the pstack_options instance, we at least know the lifetime of the singleton coincides with it.

Parameters

[in]	argc	The command-line argument count.
[in]	argv	The array of command-line arguments.

Exceptions

psystem::exception::ui_exception	Under the following conditions: If an argument looks like a process ID, but is not convertable (lexically) from a string to an integer, or is out of the range of [0, `ULONG_MAX`). If an argument is a switch that is not valid for PStack. If no PIDs were specified after all arguments are processed.
false	In the event of a non-fatal operation that interrupts the option parsing (e.g., printing the help screen), this method throws a `bool` with the value `false`.

Postcondition: Invoking the static interface is possible after successful completion of the constructor.

Warning: Only main can create and destroy the options data. Make sure to do both operations in a single-threaded context. This assumption prevents us from having to guard the global data, check for nullptr, and so on.

pstack::pstack_options::~pstack_options ( )

noexcept

Deallocate the options instance.

Postcondition: Invoking the static interface results in undefined behavior.

Member Function Documentation

void pstack::pstack_options::dump_arguments ( pstack_options::options_data const & d )

staticprivatenoexcept

Output all the command-line data to stdout.

Parameters

[in] d The internal data of the pstack_options instance.

bool pstack::pstack_options::get_image_symbols ( )

staticnoexcept

Should PStack search modules on disk for symbols rather than using built-in libraries?

The built-in debugging symbol libraries do not always find the symbols they need to generate a detailed stack trace. MinGW executables often cause this issue. This flag tells PStack to use our own home-grown solution.

Returns: true if this option is active. The default is false.

Todo:: Not using this yet.

void pstack::pstack_options::print_usage ( )

staticnoexcept

Print command-line help information to the screen.

Essentially, this is instructing the user what parameters this pstack_options class understands.

void pstack::pstack_options::print_usage ( const char *const prog_name )

staticprivatenoexcept

Print command-line help information to the screen.

Essentially, this is instructing the user what parameters this pstack_options class understands. Because print_usage() relies on the option instance being initialized, this version exists to provide the required information without the requirement. The presence of prog_name is illogical as a public API, hence the private access restriction.

Parameters

[in] prog_name The name of the application from the command-line.

void pstack::pstack_options::print_version_info ( )

staticnoexcept

Output information about the PStack's version to the screen.

This also displays PSystem information, as PStack relies upon that system.

pstack_options::pid_list const & pstack::pstack_options::process_id_list ( )

staticnoexcept

Access the list of process IDs specified on the command-line.

Returns: A collecion of PIDs. It is valid for the lifetime of the pstack_options instance.

psystem::tstring const & pstack::pstack_options::program_name ( )

staticnoexcept

Access the name this program was invoked with.

Returns: The program name. It is valid for the lifetime of the pstack_options instance.

bool pstack::pstack_options::search_all_threads ( )

staticnoexcept

Should PStack output stack traces for all threads?

Returns: true if this option is active. The default is true.

bool pstack::pstack_options::show_debug ( )

staticnoexcept

Should the user output verbose debug information?

Returns: true if this option is active. The default is false.

bool pstack::pstack_options::show_error ( )

staticnoexcept

Should the user output errors in the flow of execution?

Returns: true if this option is active. The default is true.

bool pstack::pstack_options::show_frames ( )

staticnoexcept

Should PStack output frame pointers for each stack frame?

Returns: true if this option is active. The default is false.

bool pstack::pstack_options::show_info ( )

staticnoexcept

Should the user output extra informational messaging?

Returns: true if this option is active. The default is false.

void pstack::pstack_options::try_pid ( char const * arg )

private

Try to interpret a CLI parameter as a process ID.

This method attempts to convert a string using the C++ numerical (literal) token's syntax. That is, strings that begin with "0x" will be interpreted as hexadecimal, those that begin with "0" will be assumed to be octal, and all others will be assumed to be decimal.

Parameters

[in] arg The string to parse. It cannot be nullptr.

Exceptions

psystem::exception::ui_exception If arg input does not consist entirely of text that can be converted to a psystem::process_id_t data type. The resulting value must also be a positive integer that is less than ULONG_MAX.

void pstack::pstack_options::try_switch ( char arg )

private

Try to alter the options data based on a single character CLI switch.

If the user asks for version information or command-line option help, this method will print that to the command line.

Parameters

[in] arg The single-letter command-line switch to parse.

Exceptions

psystem::exception::ui_exception	If the user specified a switch that is not valid for PStack.
false	In the event of a non-fatal operation that interrupts the option parsing (e.g., printing the help screen), this method throws a `bool` with the value `false`.

Todo:: Either throw a better exception type (help_exception) or perhaps alter the flow so that a return value can present the same behavior.

Todo:: Use administrative privs if possible

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

include/pstack/pstack_options.hpp
src/pstack/pstack_options.cpp

Classes

Type Definitions

Option Observers

Informational Functions

Construction / Destruction

Private Utilities

Member Data

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation