TinmanException

Description

class Tinman.Core.TinmanException

This is the base exception class of the Tinman Library.

When an instance of TinmanException (and not one of its subclasses) is thrown, this means that an unexpected error has occurred. An application may catch such errors and try to continue, consuming the provided error information, for example by creating a problem report.

Subclasses of TinmanException are used to distinguish between error types that an application can respond to by catching specific exception types only. Low-level error information is provided using TinmanError objects. Subclasses may also provide additional error information, on a higher application level.

The following exceptions are thrown in DEBUG mode only and indicate programming mistakes. These exceptions are not included in the list of thrown exceptions in the documentation of a method; instead, the preconditions and assertions are explained.

These exceptions represent expected error situations which are thrown in both DEBUG and RELEASE mode (dependent libraries may define additional exception types):

  • ConfigException
    An error related to the use of the Config API has occurred (e.g. bad syntax, bad semantic, etc.).

  • IOException
    An input / output error has occurred (e.g. accessing the filesystem, the web, etc.).

  • PoolingException
    A pooled background task has failed.

  • ValidatingException
    High-level validation has reported one or more errors.

Panic situations (i.e. fatal internal errors) are reported via Panic. Obviously, this should never happen. But if it does anyway, the reported information can be used to file a bug report (please send to: support@tinman3d.com). Information may be found in log output (see LoggingUtil), in error dump file (see TinmanErrorDump) or exception messages.

Public / Constructors

Error


public static method Error → (3)

source in : string

The error source (see TinmanError.ErrorSource).

message opt : string = null

The error message.

errorInfo opt : TinmanError = null

The error cause.

returns → TinmanException

The ready-to-throw exception.

An unexpected error has occurred.

NativeError

3 overloads


public static method NativeError1 → (2)

source in : string

The error source (see TinmanError.ErrorSource).

functionName in : string

The function name.

returns → TinmanException

The ready-to-throw exception.

A native function call has failed although it was expected to succeed.

The error code is retrieved via FetchLastError.


public static method NativeError2 → (3)

source in : string

The error source (see TinmanError.ErrorSource).

functionName in : string

The function name.

errorCode in : int32

The native error code.

returns → TinmanException

The ready-to-throw exception.

A native function call has failed although it was expected to succeed.


public static method NativeError3 → (3)

source in : string

The error source (see TinmanError.ErrorSource).

functionName in : string

The function name.

errorCode in : string

The native error code.

returns → TinmanException

The ready-to-throw exception.

A native function call has failed although it was expected to succeed.

Public / Methods

FetchLastError


public static method FetchLastError → ()

returns → int32

The OS error code.

Fetches the OS error code of the last operation.

NativeErrorMessage

3 overloads


[Pure]
public static method NativeErrorMessage1 → (1)

functionName in : string

The function name.

returns → string

The error message.

Generates an error message for NativeError1.


[Pure]
public static method NativeErrorMessage2 → (2)

functionName in : string

The function name.

errorCode in : int32

The native error code.

returns → string

The error message.

Generates an error message for NativeError2.


[Pure]
public static method NativeErrorMessage3 → (2)

functionName in : string

The function name.

errorCode in : string

The native error code.

returns → string

The error message.

Generates an error message for NativeError3.

Panic


public static method Panic → (2)

source in : string

The error source (see TinmanError.ErrorSource).

message opt : string = null

The panic message.

A panic situation has occurred.

A panic is an unrecoverable problem usually caused by programming errors at development time that are reported by throwing an exception in DEBUG mode. In RELEASE mode, panic handling is platform dependent, to allow more aggressive code optimizations (e.g. noexcept in C++):

  • C# / RELEASE :
    A TinmanException is thrown.

  • C++ / RELEASE :
    No action is taken.

For the RELEASE mode case, dummy code is in place to make the compiler happy. Dummy code should be as simple as possible, for example a single return or use of default values. It is assumed that dummy code will never be executed.

Panic_ShouldNeverHappen


public static method Panic_ShouldNeverHappen → (2)

source in : string

The error source (see TinmanError.ErrorSource).

exception in : TinmanException

The impossible exception that has been caught.

This code path will never be executed; static code analysis may fail to detect this, but the developer (hopefully) knows better.

This factory method is only used to satisfy coding guidelines and to make the compiler happy.

Panic_UnknownEnum

2 overloads


public static method Panic_UnknownEnum1 → (3)

source in : string

The error source (see TinmanError.ErrorSource).

name in : string

Name of the enumeration.

ordinal in : string

The ordinal number of the enumeration item.

A panic situation has occurred (unknown enum item).


public static method Panic_UnknownEnum2 → (3)

source in : string

The error source (see TinmanError.ErrorSource).

name in : string

Name of the enumeration.

ordinal in : int32

The ordinal number of the enumeration item.

A panic situation has occurred (unknown enum item).

PanicHandler


public static method PanicHandler → (1)

handler in : PanicDelegate

The panic handle or null to use the default behaviour.

Optionally, a panic handler may be specified which will be called in a panic situation, instead of performing the default behaviour as described for Panic.

Public / Attributes

ErrorInfo


public attribute ErrorInfo → (get)

value : TinmanError

[not-null]
The TinmanError object.

The TinmanError object that describes the error that has occurred.

Source


public attribute Source → (get)

value : string

The error source tag.

The error source (see TinmanError.ErrorSource).

Protected / Constructors

TinmanException


protected constructor TinmanException → (3)

source in : string

The error source (see TinmanError.ErrorSource).

message in : string

The error message.

cause opt : TinmanError = null

Optional error cause.

Creates a new exception.

Protected / Attributes

NeedsStacktrace


protected virtual attribute NeedsStacktrace → (get)

value : bool

true to include a stack-trace, false to omit it.

Include a stack-trace in ErrorInfo?