ipc::transport::error Namespace Reference

Namespace containing the ipc::transport module's extension of boost.system error conventions, so that that API can return codes/messages from within its own new set of error codes/messages. More...

Enumerations
enum class	Code {   S_SENDS_FINISHED_CANNOT_SEND = S_CODE_LOWEST_INT_VALUE , S_RECEIVES_FINISHED_CANNOT_RECEIVE , S_LOW_LVL_TRANSPORT_HOSED_CANNOT_SEND , S_LOW_LVL_TRANSPORT_HOSED_CANNOT_RECEIVE ,   S_LOW_LVL_TRANSPORT_HOSED , S_LOW_LVL_UNEXPECTED_STREAM_PAYLOAD_BEYOND_HNDL , S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE , S_BLOB_RECEIVER_GOT_NON_BLOB ,   S_RECEIVER_IDLE_TIMEOUT , S_PROTOCOL_NEGOTIATION_OPPOSING_VER_INVALID , S_PROTOCOL_NEGOTIATION_OPPOSING_VER_TOO_OLD , S_INVALID_ARGUMENT ,   S_TIMEOUT , S_INTERRUPTED , S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER , S_MQ_MESSAGE_SIZE_OVER_OR_UNDERFLOW ,   S_MQ_BIPC_MISC_LIBRARY_ERROR , S_BLOB_STREAM_MQ_SENDER_EXISTS , S_BLOB_STREAM_MQ_RECEIVER_EXISTS , S_BLOB_STREAM_MQ_RECEIVER_BAD_CTL_CMD ,   S_SYNC_IO_WOULD_BLOCK , S_END_SENTINEL }
	All possible errors returned (via Error_code arguments) by ipc::transport functions/methods outside of system-triggered errors such as boost::asio::error::connection_reset. More...

Functions
Error_code	make_error_code (Code err_code)
	Given a Code enum value, creates a lightweight Error_code (a/k/a boost.system error_code) representing that error. More...
std::ostream &	operator<< (std::ostream &os, Code val)
	Serializes a transport::error::Code to a standard output stream. More...
std::istream &	operator>> (std::istream &is, Code &val)
	Deserializes a transport::error::Code from a standard input stream. More...

Variables
constexpr int	S_CODE_LOWEST_INT_VALUE = 1
	Numeric value of the lowest Code.

Detailed Description

Namespace containing the ipc::transport module's extension of boost.system error conventions, so that that API can return codes/messages from within its own new set of error codes/messages.

Note that many errors ipc::transport might report are system errors and would not draw from this set of codes/messages but rather from boost::asio::error or boost::system::errc (possibly others). (If you're familiar with the boost.system framework, you'll know such mixing is normal – in fact arguably one of its strengths.)

See also

ipc::transport::struc::error which covers errors from the structured layer (ipc::transport::struc). The present namespace applies to unstructured/lower-level traffic or to both that and structured/higher-level.

See flow's flow::net_flow::error doc header which was used as the model for this and similar. As of this writing there is discussion there useful for someone new to boost.system error reporting.

Enumeration Type Documentation

Code

enum class ipc::transport::error::Code

strong

All possible errors returned (via Error_code arguments) by ipc::transport functions/methods outside of system-triggered errors such as boost::asio::error::connection_reset.

These values are convertible to Error_code (a/k/a boost::system::error_code) and thus extend the set of errors that Error_code can represent.

Enumerator
S_SENDS_FINISHED_CANNOT_SEND	Will not send message: local user already ended sending via API marking this.
S_RECEIVES_FINISHED_CANNOT_RECEIVE	Will not receive message: either opposing user sent graceful-close via API.
S_LOW_LVL_TRANSPORT_HOSED_CANNOT_SEND	Unable to send outgoing traffic: an earlier-reported, or at least logged, system error had hosed the underlying transport mechanism.
S_LOW_LVL_TRANSPORT_HOSED_CANNOT_RECEIVE	Unable to receive incoming traffic: an earlier-reported, or at least logged, system error had hosed the underlying transport mechanism.
S_LOW_LVL_TRANSPORT_HOSED	Unable to access low-level details: an earlier-reported system error had hosed the underlying transport mechanism.
S_LOW_LVL_UNEXPECTED_STREAM_PAYLOAD_BEYOND_HNDL	Unable to receive incoming traffic: message contains more than: 1 blob plus 0-1 native handles.
S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE	User protocol-code mismatch: local user-provided storage cannot fit entire message received from opposing peer.
S_BLOB_RECEIVER_GOT_NON_BLOB	User protocol-code mismatch: local user expected blob only and no native handle; received at least the latter.
S_RECEIVER_IDLE_TIMEOUT	No messages (optional auto-pings or otherwise) have been received; optionally configured timeout exceeded. If a session::Session emitted this error, the session is now hosed due to master channel idle timeout indicating poor health of the opposing side or the system.
S_PROTOCOL_NEGOTIATION_OPPOSING_VER_INVALID	In protocol negotiation, opposing side sent invalid version value (not positive, not a number, etc.); the comm pathway must close.
S_PROTOCOL_NEGOTIATION_OPPOSING_VER_TOO_OLD	In protocol negotiation, opposing side reported its newest protocol version is even older than the most backwards-compatible (oldest, smallest) version we speak; the comm pathway must close.
S_INVALID_ARGUMENT	User called an API with 1 or more arguments against the API spec.
S_TIMEOUT	A (usually user-specified) timeout period has elapsed before a blocking operation completed.
S_INTERRUPTED	A blocking operation was intentionally interrupted or preemptively canceled.
S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER	Async completion handler is being called prematurely, because underlying object is shutting down, as user desires.
S_MQ_MESSAGE_SIZE_OVER_OR_UNDERFLOW	Low-level message queue send-op buffer overflow (> max size) or receive-op buffer underflow (< max size).
S_MQ_BIPC_MISC_LIBRARY_ERROR	Low-level message queue: boost.interprocess emitted miscellaneous library exception sans a system code; a WARNING message at throw-time should contain all possible details.
S_BLOB_STREAM_MQ_SENDER_EXISTS	Message-queue blob stream outgoing-direction peer could not be created, because one already exists at that name.
S_BLOB_STREAM_MQ_RECEIVER_EXISTS	Message-queue blob stream incoming-direction peer could not be created, because one already exists at that name.
S_BLOB_STREAM_MQ_RECEIVER_BAD_CTL_CMD	Message-queue blob stream peer received a malformed internal-use message from opposing side.
S_SYNC_IO_WOULD_BLOCK	A sync_io operation could not immediately complete; it will complete contingent on active async-wait event(s).
S_END_SENTINEL	SENTINEL: Not an error. This Code must never be issued by an error/success-emitting API; I/O use only.

Function Documentation

make_error_code()

Error_code ipc::transport::error::make_error_code

(

Code

err_code

)

Given a Code enum value, creates a lightweight Error_code (a/k/a boost.system error_code) representing that error.

This is needed to make the boost::system::error_code::error_code<Code>() template implementation work. Or, slightly more in English, it glues the (completely general) Error_code to the (ipc::transport-specific) error code set ipc::transport::error::Code, so that one can implicitly covert from the latter to the former.

Parameters

err_code

The enum value.

Returns

A corresponding Error_code.

operator<<()

std::ostream & ipc::transport::error::operator<<	(	std::ostream &	os,
		Code	val
	)

Serializes a transport::error::Code to a standard output stream.

The output string is compatible with the reverse istream>> operator.

Rationale

This shall print a representation that looks like the identifier in C++ code; e.g., Code::S_INVALID_ARGUMENT => "INVALID_ARGUMENT". Nevertheless, when printing an Error_code storing a Code, continue to do the standard thing: output the Error_code (which will print the category name, in our case, something like "ipc/transport"; and the numeric enum value) itself plus its .message() (which will print a natural-language message). Naturally that technique will work with any Error_code, including but not limited to one storing a Code.

So why does the present operator<< even exist? Answer: Primarily it's in order to enable a consistent, yet human-friendly, machinery of serializing/deserializing Codes. No such machinery exists for general Error_code, and specifying an Error_code in an input stream would probably invovle (at least) providing a numeric value; but we can still provide a symbolic [de]serialization for specifically transport::error::Code. Why did we want that? Answer: The original use case was in testing scenarios, to easily specify an expected outcome of an ipc::transport API call symbolically instead of resorting to numeric enum values (it's nicer to say "expect INVALID_ARGUMENT" rather than "expect 13" – though incidentally the latter also works).

Parameters

os	Stream to which to serialize.
val	Value to serialize.

Returns

os.

operator>>()

std::istream & ipc::transport::error::operator>>	(	std::istream &	is,
		Code &	val
	)

Deserializes a transport::error::Code from a standard input stream.

Reads up to but not including the next non-alphanumeric-or-underscore character; the resulting string is then mapped to a log::Sev. If none is recognized, Code::S_END_SENTINEL is the result. The recognized values are:

• "1", "2", ...: Corresponds to the int conversion of that Code.
• Case-insensitive encoding of the non-S_-prefix part of the actual Code member; e.g., "INVALID_ARGUMENT" (or "invalid_argument" or "Invalid_argument" or...) for Code::S_INVALID_ARGUMENT. This enables a few I/O things to work, including parsing from config file/command line via and conversion from string via boost::lexical_cast.

Parameters

is	Stream from which to deserialize.
val	Value to set.

Returns

is.