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).

◆ 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.