Intel® RealSense™ Cross Platform API
Intel Realsense Cross-platform API
|
librealsense project relies on exception-based error handling. This page will review the expectations, mechanics and the post-conditions implied by this model, compared to return-code based error handling.
Whenever librealsense encounters failure of a system call it will record it as either WARNING
or ERROR
log entry. (see ./troubleshooting.md "troubleshooting.md" to enable librealsense log) If the problem is internally recoverable, it will be marked as WARNING
. If the problem requires user intervention, exception
object will be created together with ERROR
log entry.
If the operation was not issued by the user, but rather by one of the background threads, the exception should never reach the global signal handler of the process. Instead, it will be converted to rs_notification
object, and sent to the user through the notifications callback.
If the operation was issued by the user, exception
object will be safely marshalled between module boundaries at rs.cpp
level, by converting it to rs_error
object. This new object can be safely consumed by C program. If the application is using rs.hpp
, the C++ wrapper will convert rs_error
object back to an exception object. This exception will always derive from rs2::error
and std::runtime_error
regardless of type of exception that caused it.
The user is safe to assume that:
Note Regarding Disconnects: While librealsense2 provides a mechanism to get notified and recover from camera disconnects, any operations issued between the physical disconnect and the notification are bound to fail. rsutil2.hpp
provides a convenience class for dealing with camera disconnects, including a way to query if the device is still connected.
Note Regarding Destructors: The only case when an exception will be handled internally without notifying the user, is as part of object destruction flow. For example, when the device
object is being destroyed we might get system call failures due to the device being disconnected. Any such errors will be documented in the log but not risen to the user to avoid throw-in-destructor problems.
In addition to string representation of what went wrong, librealsense exceptions also provide get_failed_function
and get_failed_args
methods to query failed function names and argument values respectively, and error type. rs.hpp
will automatically map error types into the following inheritance structure:
Getting rs2::error
and not one of the concrete error classes could be considered a bug. This inheritance structure lets the user organize his code, from the most specific case to the most general:
With current design, there is no way to propagate exceptions raised inside user callbacks into the library. If user callback raises an exception, such event will be documented in the log as ERROR
.