flow::error Namespace Reference

Flow module that facilitates working with error codes and exceptions; essentially comprised of niceties on top boost.system's error facility. More...

Classes
class	Runtime_error
	An std::runtime_error (which is an std::exception) that stores an Error_code. More...

Functions
template<typename Func , typename Ret >
bool	exec_and_throw_on_error (const Func &func, Ret *ret, Error_code *err_code, util::String_view context)
	Helper for FLOW_ERROR_EXEC_AND_THROW_ON_ERROR() macro that does everything in the latter not needing a preprocessor. More...
template<typename Func >
bool	exec_void_and_throw_on_error (const Func &func, Error_code *err_code, util::String_view context)
	Equivalent of exec_and_throw_on_error() for operations with void return type. More...

Detailed Description

Flow module that facilitates working with error codes and exceptions; essentially comprised of niceties on top boost.system's error facility.

As of this writing, we feel the latter facility is fantastic and quite complete; so as of this writing flow::error is intended to contain only minor syntactic-sugary items.

Note

Flow uses the convention wherein error-related facilities of a particular Flow module X (in namespace flow::X) – especially in particular X's dedicated error code set, if any – are to reside in namespace flow::X::error, mirroring the naming of up-one-level-from-that flow::error.

See also

flow::Error_code whose doc header introduces the error-emission conventions used in all Flow modules.

Function Documentation

exec_and_throw_on_error()

template<typename Func , typename Ret >

bool flow::error::exec_and_throw_on_error	(	const Func &	func,
		Ret *	ret,
		Error_code *	err_code,
		util::String_view	context
	)

Helper for FLOW_ERROR_EXEC_AND_THROW_ON_ERROR() macro that does everything in the latter not needing a preprocessor.

Probably not to be called except by that macro.

This function is the meat of it. I omit details, since they are explained in FLOW_ERROR_EXEC_AND_THROW_ON_ERROR() doc header. The present function does what is described therein – except for preprocessor-requiring actions:

Preprocessor is needed to (1) supply halfway-decent "context" (file/line #/etc.) info to the exception object; and (2) to trigger the invoker of the macro (the actual user-facing API or very close to it) to return XYZ to its caller (user code or very close to it). So this function cannot do that, but instead it respectively (1) takes the context string as an argument; and (2) returns true if and only if the invoker of the macro should in fact immediately return the value *ret, where ret is an "out" argument to the present function.

Note

ATTENTION! This is a (rare) case where documentation is more complicated than just looking at the implementation. This embarrassingly verbose doc header is sort of a pedantic formality in this particular (rare) case and is probably not worth reading for most people.

Template Parameters

Func	Any type such that given an instance Func f, the expression r = f(&e_c) is valid, assuming e_c is an Error_code, and r is a Ret. In practice, this is usually the insane type of whatever concoction lambda or bind() conjures out of a plain, hard-working method like Peer_socket::send() and a bunch of innocent, API user-originated arguments thereto.
Ret	The return type of the operation func(). Should equal ARG_ret_type of FLOW_ERROR_EXEC_AND_THROW_ON_ERROR().

Parameters

func	The operation, with the return type and argument as described above in Func template argument doc, that performs whatever possibly error-generating actions are being wrapped by all this; and returns whatever value is intended for the ultimate API caller. The Error_code* passed into func() will NOT be null; thus func() must NOT throw Runtime_error on error.
ret	Non-null pointer to a value into which the present function will place the return value of func(), if indeed it executes the latter (and thus true is returned).
err_code	Null; or non-null pointer to an error code in memory; probably originating from the API caller. *err_code is set if and only if err_code was non-null; and func() was executed (thus true returned); and func() encountered an error.
context	Value suitable for the context argument of Runtime_error constructor. Most likely this should be something it takes little to no runtime computation to obtain; so either your own string literal; or FLOW_UTIL_WHERE_AM_I_LITERAL().

Returns

true if and only if err_code is null; and therefore func() was called. false otherwise (i.e., err_code is not null; nothing was done; and the caller should perform the equivalent of func() while safely assuming *err_code may be assigned to upon error).

Definition at line 128 of file error.hpp.

exec_void_and_throw_on_error()

template<typename Func >

bool flow::error::exec_void_and_throw_on_error	(	const Func &	func,
		Error_code *	err_code,
		util::String_view	context
	)

Equivalent of exec_and_throw_on_error() for operations with void return type.

Unlike the latter function, however, the present function is to be used directly as opposed to via macro.

Template Parameters

Func	Any type such that given an instance Func f, the expression f(&e_c) is valid, assuming e_c is an Error_code.

Parameters

func	The operation, with the return type void and argument as described above in Func template argument doc, that performs whatever possibly error-generating actions are being wrapped by all this. The Error_code* passed into func() will NOT be null; thus func() must NOT throw Runtime_error on error.
err_code	See exec_and_throw_on_error().
context	See exec_and_throw_on_error().

Returns

See exec_and_throw_on_error().

Definition at line 168 of file error.hpp.

Referenced by flow::net_flow::Event_set::close(), flow::net_flow::Peer_socket::close_abruptly(), and flow::net_flow::Node::interrupt_all_waits().

Here is the caller graph for this function: