Return values

Standard return values of functions in storage manager. More...

Classes
class	w_rc_t
	Return code for most functions and methods. More...

Macros
#define	RC(e)   w_rc_t(__FILE__, __LINE__, e)
	Normal error-case return. Create a return code with the current file, line, and error code x. This is the normal way to return from a method or function. More...
#define	RC_AUGMENT(rc)   w_rc_t(rc, __FILE__, __LINE__)
	Augment stack trace. Add stack trace information (file, line) to a return code. This is the normal way to return from a method or function upon receiving an error from a method or function that it called. Used by W_DO(x), W_DO_MSG(x,m), and W_COERCE(x) e.g. w_rc_t rc = create_file(f); if (rc.is_error()) return RC_AUGMENT(rc); rc = close_file(f);. More...
#define	RC_APPEND_MSG(rc, m)
	Appends more arbitrary string information to the return code. More...
#define	W_RETURN_RC_MSG(e, m)
	Retrun with a return code that contains the given error code and additional message. More...
#define	W_DO(x)
	Call a method or function x. This macro is the normal idiom for calling a method or function. Most methods and functions return a w_rc_t. This macro calls x and checks its returned value. If an error is encountered, it immediately returns from the current function or method, augmenting the stack trace held by the return code. More...
#define	W_DO_MSG(x, m)
	Call a method or function x. More...
#define	W_COERCE(x)
	Call a function or method x, fail catastrophically if error is returned. More...
#define	W_COERCE_MSG(x, m)
	Same as W_COERCE(x) but adds a string message before croaking. More...
#define	W_FATAL(e)   W_COERCE(RC(e))
	Croak with the error code e. More...
#define	W_FATAL_MSG(e, m)   W_COERCE_MSG(RC(e), m)
	Croak with the error code e and message m. More...
#define	W_IGNORE(x)   ((void) x.is_error())
	Invoke x and ignore its result. More...

Variables
const uint16_t	MAX_RCT_STACK_DEPTH = 8
	Constant to define maximum stack trace depth for w_rc_t. More...

Detailed Description

Standard return values of functions in storage manager.

The storage manager is written with programming idioms to make sure all return codes are checked, and as a user of the storage manager, you strongly encouraged to use these idioms.

It is especially important that you understand the storage manager's return code type, w_rc_t. Most of the storage manager methods return this type. The return code type is a dynamically-allocated class instance (except when RCOK, the default, non-error code, is returned: this is a static constant).

Several macros defined in w_rc.h support writing and using methods and functions that return a w_rc_t.

w_rc_t func(...) {
    W_DO(ss_m::create_assoc(...));
    return RCOK;
}

The W_DO macro returns whatever the called function returns if that return code was an error code, otherwise, it falls through to the code below the macro call. This is the most-often used idiom.

The RC_* macros let you construct a return code for a return value from a function. The normal, non-error return code is RCOK.

Individual error codes and corresponding error messages are described in detail by Error code and error messages. There you wil also see how to create your own return codes.

Difference from Shore-MT

Like many other modules in the storage manager, these classes went through a complete refactoring when we convert Shore-MT to Foster-Btrees. Virtually the only thing that was unchanged is the name (w_rc_t, RCOK, W_DO, etc). We do not use TLS for w_rc_t. We do not have a perl script to generate error code enum. etc. This file is completely independent and header-only. Just include w_rc.h to use.

Macro Definition Documentation

RC

#define RC

(

e

)

w_rc_t(__FILE__, __LINE__, e)

Normal error-case return. Create a return code with the current file, line, and error code x. This is the normal way to return from a method or function.

RC_APPEND_MSG

#define RC_APPEND_MSG	(		rc,
			m
	)

Value:

do {                            \
    std::stringstream os;       \
    os m;                       \
    rc.append_custom_message(os.str().c_str()); \
} while (0)

Appends more arbitrary string information to the return code.

Add a char string representing more information to a return code. Used by W_RETURN_RC_MSG(e, m), W_COERCE_MSG(x, m)

RC_AUGMENT

#define RC_AUGMENT

(

rc

)

w_rc_t(rc, __FILE__, __LINE__)

Augment stack trace. Add stack trace information (file, line) to a return code. This is the normal way to return from a method or function upon receiving an error from a method or function that it called. Used by W_DO(x), W_DO_MSG(x,m), and W_COERCE(x) e.g. w_rc_t rc = create_file(f); if (rc.is_error()) return RC_AUGMENT(rc); rc = close_file(f);.

W_COERCE

#define W_COERCE

(

x

)

Value:

do {                            \
    w_rc_t __e = (x);           \
    if (__e.is_error())  {      \
        __e = RC_AUGMENT(__e);  \
        __e.fatal();            \
    }                           \
} while (0)

Call a function or method x, fail catastrophically if error is returned.

This macro is like W_DO(x), but instead of returning in the error case, it fails catastrophically. It is used in cases such as these:

• Temporary place-holder where the coder hasn't written the failure-handling code
• The calling function or method API has no means to return error information, and this case hasn't yet been accommodated.
• The called x should never return an error in this case, and doing so would indicate a programming error.

• The called x never returns an error at the time the calling code is written, and should the called code x change, the calling code should probably be adjusted to handle any new error.

  The call to __e.fatal() prints the stack trace and additional information associated with the w_rc_t before it croaks.

W_COERCE_MSG

#define W_COERCE_MSG	(		x,
			m
	)

Value:

do {                             \
    w_rc_t __em = (x);           \
    if (__em.is_error())  {      \
        __em = RC_AUGMENT(__em); \
        RC_APPEND_MSG(__em, m);  \
        __em.fatal();            \
    }                            \
} while (0)

Same as W_COERCE(x) but adds a string message before croaking.

W_DO

#define W_DO

(

x

)

Value:

do {                    \
    w_rc_t __e(x);      \
    if (__e.is_error()) {return RC_AUGMENT(__e);} \
} while (0)

Call a method or function x. This macro is the normal idiom for calling a method or function. Most methods and functions return a w_rc_t. This macro calls x and checks its returned value. If an error is encountered, it immediately returns from the current function or method, augmenting the stack trace held by the return code.

W_DO_MSG

#define W_DO_MSG	(		x,
			m
	)

Value:

do {                            \
    w_rc_t __e = (x);           \
    if (__e.is_error()) {       \
        RC_AUGMENT(__e);        \
        RC_APPEND_MSG(__e, m);  \
        return __e;             \
    }                           \
} while (0)

Call a method or function x.

Like W_DO, but any error returned contains the additional information message m.

W_FATAL

#define W_FATAL

(

e

)

W_COERCE(RC(e))

Croak with the error code e.

W_FATAL_MSG

#define W_FATAL_MSG	(		e,
			m
	)		W_COERCE_MSG(RC(e), m)

Croak with the error code e and message m.

W_IGNORE

#define W_IGNORE

(

x

)

((void) x.is_error())

Invoke x and ignore its result.

W_RETURN_RC_MSG

#define W_RETURN_RC_MSG	(		e,
			m
	)

Value:

do {                                    \
    w_rc_t __e(__FILE__, __LINE__, e);  \
    RC_APPEND_MSG(__e, m);              \
    return __e;                         \
} while (0)

Retrun with a return code that contains the given error code and additional message.

Variable Documentation

MAX_RCT_STACK_DEPTH

const uint16_t MAX_RCT_STACK_DEPTH = 8

Constant to define maximum stack trace depth for w_rc_t.