|
Flow-IPC 1.0.0
Flow-IPC project: Full implementation 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...
Classes | |
| class | Category |
| The boost.system category for errors returned by the ipc::transport module. 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. More... | |
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 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.
enum with the codes, like error::Code; (2) an int-to-string message table function, for log messages; and (3) a brief const char* identifying the code set, for log messages. The rest is the boiler-plate, but all of it seems to either already be accepably brief, and where something isn't quite so, I can't think of any obvious way to factor it out. Of course a macro-based "meta-language" is always a possibility, as we did in flow::log, but in this case it doesn't seem worth it at all.
|
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.
When you add a value to this enum, also add its description to error.cpp’s Category::message(). This description must be identical to the description in the /// comment below, or at least as close as possible. This mirrors Flow's convention.
When you add a value to this enum, also add its symbolic representation to error.cpp's error.cpp's Category::code_symbol(). This string must be identical to the symbol, minus the S_; e.g., Code::S_INVALID_ARGUMENT => "INVALID_ARGUMENT". This enables the consistent and human-friendly serialization<<and deserialization>>` of a Code w/r/t standard streams.
If, when adding a new revision of the code, you add a value to this enum, add it to the end, but ahead of Code::S_END_SENTINEL. If, when adding a new revision of the code, you deprecate a value in this enum, do not delete it from this enum. Instead mark it as deprecated here and then remove it from Ipc_transport_category::message().
Errors that indicate apparent logic bugs (in other words, assertions that we were too afraid to write as actual assert()s) should be prefixed with S_INTERNAL_ERROR_, and their messages should also indicate "Internal error: ". This mirrors Flow's convention.
| 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. |
| 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.
| err_code | The enum value. |
Definition at line 91 of file error.cpp.
References ipc::transport::error::Category::S_CATEGORY.
| 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.
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).
| os | Stream to which to serialize. |
| val | Value to serialize. |
os. Definition at line 241 of file error.cpp.
References ipc::transport::error::Category::code_symbol().
| 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:
int conversion of that Code.string via boost::lexical_cast.| is | Stream from which to deserialize. |
| val | Value to set. |
is. Definition at line 247 of file error.cpp.
References S_CODE_LOWEST_INT_VALUE, and S_END_SENTINEL.
|
constexpr |
Numeric value of the lowest Code.
Definition at line 56 of file error.hpp.
Referenced by operator>>().
1.9.4