Sawyer Namespace Reference

Description

Sawyer support library.

All Sawyer functionality except for some C preprocessor macros exists inside this namespace. Most of the macros begin with the string "SAWYER_".

See this page for an overview of the Sawyer library.

Namespaces
namespace	Assert
	Run-time logic assertions.
namespace	Attribute
	Attributes attached to other objects.
namespace	Boost
	Boost Graph Library API for Sawyer::Container::Boost.
namespace	CommandLine
	Parses program command line switches and arguments.
namespace	Container
	Container classes that store user-defined values.
namespace	Document
	Documentation-related entities.
namespace	FileSystem
	File system utilities.
namespace	Message
	Formatted diagnostic messages emitted to various backends.
namespace	ProgressBarSettings
	Global settings for progress bars.
namespace	Tree
	Tree data structure.
namespace	Type
	Data types.
namespace	Yaml
	YAML parser and unparser.

Classes
class	BitFlags
	Stores a vector of enum bit flags. More...
class	Cached
	Implements cache data members. More...
class	Callbacks
class	DefaultAllocator
	Default allocator. More...
class	Error
	Error value. More...
class	Error< char[N]>
struct	is_invocable
class	LockGuard2
	Locks multiple mutexes. More...
class	LockGuard2< NullMutex >
class	MultiInstanceTls
	Thread local data per object instance. More...
struct	MultiThreadedTag
	Tag indicating that an algorithm or API should assume multiple threads. More...
class	Nothing
	Represents no value. More...
class	NullBarrier
class	NullLockGuard
class	NullMutex
class	Ok
	Success value. More...
class	Ok< char[N]>
class	Optional
	Holds a value or nothing. More...
class	PoolAllocatorBase
	Small object allocation from memory pools. More...
class	ProgressBar
	Progress bars. More...
class	ProgressBarImpl
class	ProxyAllocator
	Allocator proxy. More...
class	Result
	Result containing a value or an error. More...
class	SharedFromThis
	Creates SharedPointer from this. More...
class	SharedObject
	Base class for reference counted objects. More...
class	SharedPointer
	Reference-counting intrusive smart pointer. More...
struct	SingleThreadedTag
	Tag indicating that an algorithm or API can assume only a single thread. More...
class	SmallObject
	Small object support. More...
class	StackAllocator
	Stack-like allocator. More...
class	Stopwatch
	Simple elapsed time. More...
struct	SynchronizationTraits
	Traits for thread synchronization. More...
struct	SynchronizationTraits< MultiThreadedTag >
struct	SynchronizationTraits< SingleThreadedTag >
class	TemporaryCallback
class	ThreadWorkers
	Work list with dependencies. More...
class	Time
	Represents an ISO 8601 time point. More...
class	WorkFifo
	First-in-first-out work queue. More...

Typedefs
typedef PoolAllocatorBase< sizeof(void *), 4, 32, 40960, SingleThreadedTag >	UnsynchronizedPoolAllocator
	Small object allocation from memory pools.
typedef PoolAllocatorBase< sizeof(void *), 4, 32, 40960, MultiThreadedTag >	SynchronizedPoolAllocator
	Small object allocation from memory pools.

Functions
template<typename T , typename U >
bool	operator== (const Optional< T > &lhs, const U &)
template<typename T , typename U >
bool	operator!= (const Optional< T > &lhs, const U &)
template<class IntegralType >
Sawyer::Optional< typename std::enable_if< std::is_integral< IntegralType >::value, IntegralType >::type >	toDigit (char ch, IntegralType radix=10)
	Convert a character to a numeric digit.
template<class IntegralType >
std::enable_if< std::is_integral< IntegralType >::value, Sawyer::Result< IntegralType, std::string > >::type	parse (const std::string &s)
	Safely convert a string to a number.
template<class T >
Ok< T >	makeOk (const T &value)
	Conventient way to constructo an Ok value before C++17.
Ok< std::string >	makeOk (const char *s)
Ok< std::string >	makeOk (char *s)
template<class T >
Error< T >	makeError (const T &value)
	Conventient way to constructo an Error value before C++17.
Error< std::string >	makeError (const char *s)
Error< std::string >	makeError (char *s)
bool	initializeLibrary (size_t vmajor=0, size_t vminor=1, size_t vpatch=0, bool withThreads=0)
	Explicitly initialize the library.
boost::int64_t	strtoll (const char *, char **, int)
	Portable replacement for strtoll.
boost::uint64_t	strtoull (const char *, char **, int)
	Portable replacement for strtoull.
std::string	readOneLine (FILE *)
	Reads one line of input from a file.
FILE *	popen (const std::string &, const char *how)
	Semi-portable replacement for popen.
int	pclose (FILE *)
	Semi-portable replacement for pclose.
std::string	generateSequentialName (size_t length=3)
	Generate a sequential name.
void	checkBoost ()
	Check for valid boost version or abort.
std::string	thisExecutableName ()
	Return the name of this program obtained from the operating system.
template<class Pointer >
Pointer::Pointee *	getRawPointer (Pointer &ptr)
template<class T >
void	clear (SharedPointer< T > &ptr)
	Make pointer point to nothing.
std::ostream &	operator<< (std::ostream &, const Stopwatch &)
Sawyer::SynchronizationTraits< Sawyer::SingleThreadedTag >::RecursiveMutex &	bigMutex ()
size_t	fastRandomIndex (size_t n, size_t seed=0)
	Thread-safe random number generator.
std::ostream &	operator<< (std::ostream &, const Time &)
template<class WorkItems , class Functor >
void	processWorkList (WorkItems &workList, size_t maxWorkers, Functor f)
	Process work from a work list in parallel.
template<class DependencyGraph , class Functor >
void	workInParallel (const DependencyGraph &dependencies, size_t nWorkers, Functor functor)
	Performs work in parallel.
template<class DependencyGraph , class Functor , class Monitor >
void	workInParallel (const DependencyGraph &dependencies, size_t nWorkers, Functor functor, Monitor monitor, boost::chrono::milliseconds period)
	Performs work in parallel.

Typedef Documentation

UnsynchronizedPoolAllocator

typedef PoolAllocatorBase<sizeof(void*), 4, 32, 40960, SingleThreadedTag> Sawyer::UnsynchronizedPoolAllocator

Small object allocation from memory pools.

Thread safety: This allocator is not thread safe; the caller must synchronize to prevent concurrent calls.

See PoolAllocatorBase for details.

Definition at line 514 of file PoolAllocator.h.

SynchronizedPoolAllocator

typedef PoolAllocatorBase<sizeof(void*), 4, 32, 40960, MultiThreadedTag> Sawyer::SynchronizedPoolAllocator

Small object allocation from memory pools.

Thread safety: This allocator is thread safe.

See PoolAllocatorBase for details.

Definition at line 521 of file PoolAllocator.h.

Function Documentation

operator==()

template<typename T , typename U >

bool Sawyer::operator==	(	const Optional< T > &	lhs,
		const U &
	)

Definition at line 403 of file Optional.h.

operator!=()

template<typename T , typename U >

bool Sawyer::operator!=	(	const Optional< T > &	lhs,
		const U &
	)

Definition at line 409 of file Optional.h.

toDigit()

template<class IntegralType >

Sawyer::Optional< typename std::enable_if< std::is_integral< IntegralType >::value, IntegralType >::type > Sawyer::toDigit	(	char	ch,
		IntegralType	radix = 10
	)

Convert a character to a numeric digit.

If the character is valid for the specified radix, then its numeric value is returned, otherwise nothing is returned. The radix must be less than or equal to 16.

Definition at line 27 of file Parse.h.

Referenced by parse().

parse()

template<class IntegralType >

std::enable_if< std::is_integral< IntegralType >::value, Sawyer::Result< IntegralType, std::string > >::type Sawyer::parse

(

const std::string &

s

)

Safely convert a string to a number.

The input string must parse as a integer without leading white space and without trailing characters. For signed integer types, the integer may be immediately preceded by a minus ("-") or plus ("+") sign. The integer part may be preceded by a radix indicator: "0x" for hexadecimal or "0b" for binary. Octal and other bases are not supported. Digits may be separated from one another (or from the radix specifier) by a single underscore, as in "0b_0001_0010_0011_0100_0101_0110_0111_1000".

The IntegralType must be a signed or unsigned integer type of any width. The uint8_t and int8_t types are also accepted although they're aliases for unsigned char and signed char .

If a syntax error occurs, or if the magnitude of the value is too large to be represented by the specified IntegralType, then an error message is returned. The text of the message begins with either "syntax error:" or "overflow error:".

Definition at line 60 of file Parse.h.

References toDigit().

makeOk() [1/3]

template<class T >

Ok< T > Sawyer::makeOk

(

const T &

value

)

Conventient way to constructo an Ok value before C++17.

Template parameter type deduction in constructors first appeared in C++17. The standard library worked around this by using factory functions to instantiate these types without having to repeat the full type name.

Definition at line 156 of file Result.h.

Referenced by Sawyer::Result< T, E >::fmap().

makeOk() [2/3]

Ok< std::string > Sawyer::makeOk ( const char *  s )

inline

Definition at line 161 of file Result.h.

makeOk() [3/3]

Ok< std::string > Sawyer::makeOk ( char *  s )

inline

Definition at line 164 of file Result.h.

makeError() [1/3]

template<class T >

Error< T > Sawyer::makeError

(

const T &

value

)

Conventient way to constructo an Error value before C++17.

Template parameter type deduction in constructors first appeared in C++17. The standard library worked around this by using factory functions to instantiate these types without having to repeat the full type name.

Definition at line 301 of file Result.h.

Referenced by Sawyer::Result< T, E >::fmap().

makeError() [2/3]

Error< std::string > Sawyer::makeError ( const char *  s )

inline

Definition at line 306 of file Result.h.

makeError() [3/3]

Error< std::string > Sawyer::makeError ( char *  s )

inline

Definition at line 309 of file Result.h.

initializeLibrary()

bool Sawyer::initializeLibrary	(	size_t	vmajor = 0,
		size_t	vminor = 1,
		size_t	vpatch = 0,
		bool	withThreads = 0
	)

Explicitly initialize the library.

This initializes any global objects provided by the library to users. This happens automatically for many API calls, but sometimes needs to be called explicitly. It can be called as often as desired; each call checks caller-callee consistency (version number and configuration), but only the first call does any initialization. The function always returns true.

strtoll()

boost::int64_t Sawyer::strtoll	(	const char *	,
		char **	,
		int
	)

Portable replacement for strtoll.

Microsoft doesn't define this function, so we define it in the Sawyer namespace.

strtoull()

boost::uint64_t Sawyer::strtoull	(	const char *	,
		char **	,
		int
	)

Portable replacement for strtoull.

Microsoft doesn't define this function, so we define it in the Sawyer namespace.

readOneLine()

std::string Sawyer::readOneLine

(

FILE *

)

Reads one line of input from a file.

Returns one line, including any line termination. Returns an empty string at the end of the file.

generateSequentialName()

std::string Sawyer::generateSequentialName

(

size_t

length = 3

)

Generate a sequential name.

A new string is generated each time this is called.

getRawPointer()

template<class Pointer >

Pointer::Pointee * Sawyer::getRawPointer

(

Pointer &

ptr

)

Definition at line 351 of file SharedPointer.h.

clear()

template<class T >

void Sawyer::clear

(

SharedPointer< T > &

ptr

)

Make pointer point to nothing.

Clears the pointer so it points to no object. A cleared pointer is like a default-constructed pointer.

Definition at line 359 of file SharedPointer.h.

fastRandomIndex()

size_t Sawyer::fastRandomIndex	(	size_t	n,
		size_t	seed = 0
	)

Thread-safe random number generator.

Generates uniformly distributed pseudo-random size_t values. The returned value is greater than zero and less than n, where n must be greater than zero except when seeding the sequence. To seed the sequence, call with n equal to zero and a non-zero seed; all other calls must supply a zero seed value. This function uses the fastest available method for returning random numbers in a multi-threaded environment. This function is thread-safe.

Referenced by Rose::Combinatorics::shuffle().

workInParallel() [1/2]

template<class DependencyGraph , class Functor >

void Sawyer::workInParallel	(	const DependencyGraph &	dependencies,
		size_t	nWorkers,
		Functor	functor
	)

Performs work in parallel.

Creates up to the specified number of worker threads to run the tasks described in the dependencies graph (at least one thread, but not more than the number of items on which to work). The dependencies is a graph whose vertices represent individual tasks to be performed by worker threads, and whose edges represent dependencies between the task. An edge from task a to task b means that task b must complete before task a can begin. If the dependencies graph contains cycles then as much work as possible is performed and then a ContainsCycle exception is thrown.

The functor can be a class with operator(), a function pointer, or a lambda expression. If a class is used, it must be copyable and each worker thread will be given its own copy. The functor is invoked with two arguments: the ID number of the task being processed, and a reference to a copy of the task (vertex value) in the dependency graph. The ID number is the vertex ID number in the dependencies graph.

If a monitor is provided, it will be called once every period milliseconds with the following arguments: the dependencies graph, number of work items that have been completed, and the set of dependencies vertex IDs (std::set<size_t>) that are currently running.

The call does not return until all work has been completed.

Definition at line 316 of file ThreadWorkers.h.

workInParallel() [2/2]

template<class DependencyGraph , class Functor , class Monitor >

void Sawyer::workInParallel	(	const DependencyGraph &	dependencies,
		size_t	nWorkers,
		Functor	functor,
		Monitor	monitor,
		boost::chrono::milliseconds	period
	)

Performs work in parallel.

Creates up to the specified number of worker threads to run the tasks described in the dependencies graph (at least one thread, but not more than the number of items on which to work). The dependencies is a graph whose vertices represent individual tasks to be performed by worker threads, and whose edges represent dependencies between the task. An edge from task a to task b means that task b must complete before task a can begin. If the dependencies graph contains cycles then as much work as possible is performed and then a ContainsCycle exception is thrown.

The functor can be a class with operator(), a function pointer, or a lambda expression. If a class is used, it must be copyable and each worker thread will be given its own copy. The functor is invoked with two arguments: the ID number of the task being processed, and a reference to a copy of the task (vertex value) in the dependency graph. The ID number is the vertex ID number in the dependencies graph.

If a monitor is provided, it will be called once every period milliseconds with the following arguments: the dependencies graph, number of work items that have been completed, and the set of dependencies vertex IDs (std::set<size_t>) that are currently running.

The call does not return until all work has been completed.

Definition at line 323 of file ThreadWorkers.h.

References Sawyer::ThreadWorkers< DependencyGraph, Functor >::nFinished(), Sawyer::ThreadWorkers< DependencyGraph, Functor >::runningTasks(), Sawyer::ThreadWorkers< DependencyGraph, Functor >::start(), and Sawyer::ThreadWorkers< DependencyGraph, Functor >::tryWaitFor().

processWorkList()

template<class WorkItems , class Functor >

void Sawyer::processWorkList	(	WorkItems &	workList,
		size_t	maxWorkers,
		Functor	f
	)

Process work from a work list in parallel.

Processes each item in the work list by passing the item and the list of pending work to the provided functor. Up to maxWorkers work items are processed in parallel. The workList is responsible for holding the list of outstanding work items and hands them out one at a time according some priority. The WorkFifo is an example class that satisfies the WorkItems interface and hands out work items in the same order they were created. Since the functor is given a reference to the workList, wihch contains all pending work (work that hasn't started yet), the functor is able to modify the work list, such as adding additional work items.

Definition at line 69 of file WorkList.h.