foedus::ErrorStack Class Reference

Brings error stacktrace information as return value of functions. More...

Detailed Description

Brings error stacktrace information as return value of functions.

This is returned by many API functions. As it brings stacktrace information, it's more informative than just returning ErrorCode. However, note that instantiating and augmenting this stack object has some overhead.

Why not exception

A couple of reasons:

• Performance
• Portability
• Our Google C++ Coding Style overlord said so

We are not even sure what exceptions would look like in future environments. So, we don't throw or catch any exceptions in our program.

Macros to help use ErrorStack

In most places, you should use kRetOk, CHECK_ERROR(x), or ERROR_STACK(e) to handle this class. See the doucments of those macros.

Forced return code checking

An error code must be checked by some code, else it will abort with an "error-not-checked" error in stderr. We might later make this warning instead of aborting, but we should keep the current setting for a while to check for undesired coding. Once you get used to, making it sure is quite effortless.

Maximum stack trace depth

When the return code is an error code, we propagate back the stack trace for easier debugging. We could have a linked-list for this and, to ameriolate allocate/delete cost for it, a TLS object pool. Unfortunately, it causes issues in some environments and is not so readable/maintainable. Instead, we limit the depth of stacktraces stored in this object to a reasonable number enough for debugging; kMaxStackDepth. We then store just line numbers and const pointers to file names. No heap allocation. The only thing that has to be allocated on heap is a custom error message. However, there are not many places that use custom messages, so the cost usually doesn't happen.

Moveable/Copiable

This object is copiable. Further, the copy constructor and copy assignment operator are equivalent to move. Although they take a const reference, we steal its checked_ and custom_message_. This might be confusing, but much more efficient without C++11. As this object is copied so many times, we take this approach.

This class is header-only except output(), dump_and_abort(), and std::ostream redirect.

Definition at line 81 of file error_stack.hpp.

#include <error_stack.hpp>

Public Types
enum	Constants { kMaxStackDepth = 8 }
	Constant values. More...

Public Member Functions
	ErrorStack ()
	Empty constructor. More...
	ErrorStack (ErrorCode code)
	Instantiate a return code without a custom error message nor stacktrace. More...
	ErrorStack (const char *filename, const char *func, uint32_t linenum, ErrorCode code, const char *custom_message=nullptr)
	Instantiate a return code with stacktrace and optionally a custom error message. More...
	ErrorStack (const ErrorStack &other)
	Copy constructor. More...
	ErrorStack (const ErrorStack &other, const char *filename, const char *func, uint32_t linenum, const char *more_custom_message=nullptr)
	Copy constructor to augment the stacktrace. More...
ErrorStack &	operator= (const ErrorStack &other)
	Assignment operator. More...
	~ErrorStack ()
	Will warn in stderr if the error code is not checked yet. More...
bool	is_error () const
	Returns if this return code is not kErrorCodeOk. More...
ErrorCode	get_error_code () const
	Return the integer error code. More...
const char *	get_message () const
	Returns the error message inferred by the error code. More...
const char *	get_custom_message () const
	Returns the custom error message. More...
void	copy_custom_message (const char *message)
	Copy the given custom message into this object. More...
void	clear_custom_message ()
	Deletes custom message from this object. More...
void	append_custom_message (const char *more_custom_message)
	Appends more custom error message at the end. More...
uint16_t	get_stack_depth () const
	Returns the depth of stack this error code has collected. More...
uint32_t	get_linenum (uint16_t stack_index) const
	Returns the line number of the given stack position. More...
const char *	get_filename (uint16_t stack_index) const
	Returns the file name of the given stack position. More...
const char *	get_func (uint16_t stack_index) const
	Returns the function name of the given stack position. More...
int	get_os_errno () const
	Global errno of the system as of instantiation of this error stack. More...
void	verify () const
	Output a warning to stderr if the error is not checked yet. More...
void	output (std::ostream *ptr) const
	Describe this object to the given stream. More...
void	dump_and_abort (const char *abort_message) const
	Describe this object to std::cerr and then abort. More...

Static Public Member Functions
static std::string	get_recent_dump_and_abort ()
	Signal handler can get the dump information via this. More...

Friends
std::ostream &	operator<< (std::ostream &o, const ErrorStack &obj)

Member Enumeration Documentation

enum foedus::ErrorStack::Constants

Constant values.

Enumerator
kMaxStackDepth	Maximum stack trace depth.

Definition at line 84 of file error_stack.hpp.

                 {
     kMaxStackDepth = 8,
  };

Constructor & Destructor Documentation

foedus::ErrorStack::ErrorStack ( )

inline

Empty constructor.

This is same as duplicating kRetOk.

Definition at line 253 of file error_stack.hpp.

  : custom_message_(CXX11_NULLPTR), os_errno_(0), error_code_(kErrorCodeOk),
    stack_depth_(0), checked_(true) {
}

foedus::ErrorStack::ErrorStack ( ErrorCode  code )

inlineexplicit

Instantiate a return code without a custom error message nor stacktrace.

Parameters

[in]

code

Error code, either kErrorCodeOk or real errors.

This is the most (next to kRetOk) light-weight way to create/propagate a return code. Use this one if you do not need a detail information to debug the error (eg, error whose cause is obvious, an expected error that is immediately caught, etc).

Definition at line 258 of file error_stack.hpp.

  : custom_message_(CXX11_NULLPTR), os_errno_(errno), error_code_(code),
    stack_depth_(0), checked_(false) {
}

foedus::ErrorStack::ErrorStack ( const char *  filename, const char *  func, uint32_t  linenum, ErrorCode  code, const char *  custom_message = nullptr  )

inline

Instantiate a return code with stacktrace and optionally a custom error message.

Parameters

[in]	filename	file name of the current place. It must be a const and permanent string, such as what "__FILE__" returns. Note that we do NOT do deep-copy of the strings.
[in]	func	functiona name of the current place. Must be a const-permanent as well, such as "__FUNCTION__" of gcc/MSVC or C++11's func.
[in]	linenum	line number of the current place. Usually "__LINE__".
[in]	code	Error code, must be real errors.
[in]	custom_message	Optional custom error message in addition to the default one inferred from error code. If you pass a non-NULL string to this argument, we do deep-copy, so it's EXPENSIVE!

Definition at line 263 of file error_stack.hpp.

References ASSERT_ND, copy_custom_message(), and foedus::kErrorCodeOk.

  : custom_message_(CXX11_NULLPTR), os_errno_(errno), error_code_(code), stack_depth_(1),
    checked_(false) {
  ASSERT_ND(code != kErrorCodeOk);
  filenames_[0] = filename;
  funcs_[0] = func;
  linenums_[0] = linenum;
  copy_custom_message(custom_message);
}

Here is the call graph for this function:

foedus::ErrorStack::ErrorStack ( const ErrorStack &  other )

inline

Copy constructor.

Definition at line 274 of file error_stack.hpp.

References operator=().

  : custom_message_(CXX11_NULLPTR) {
  operator=(other);
}

Here is the call graph for this function:

foedus::ErrorStack::ErrorStack ( const ErrorStack &  other, const char *  filename, const char *  func, uint32_t  linenum, const char *  more_custom_message = nullptr  )

inline

Copy constructor to augment the stacktrace.

Definition at line 279 of file error_stack.hpp.

References append_custom_message(), foedus::kErrorCodeOk, kMaxStackDepth, LIKELY, and operator=().

  : custom_message_(CXX11_NULLPTR) {
  // Invariant: if kErrorCodeOk, no more processing
  if (LIKELY(other.error_code_ == kErrorCodeOk)) {
    this->error_code_ = kErrorCodeOk;
    return;
  }

  operator=(other);
  // augment stacktrace
  if (stack_depth_ != 0 && stack_depth_ < kMaxStackDepth) {
    filenames_[stack_depth_] = filename;
    funcs_[stack_depth_] = func;
    linenums_[stack_depth_] = linenum;
    ++stack_depth_;
  }
  // augment custom error message
  if (more_custom_message) {
    append_custom_message(more_custom_message);
  }
}

Here is the call graph for this function:

foedus::ErrorStack::~ErrorStack ( )

inline

Will warn in stderr if the error code is not checked yet.

Definition at line 326 of file error_stack.hpp.

References clear_custom_message(), foedus::kErrorCodeOk, LIKELY, and verify().

                               {
  // Invariant: if kErrorCodeOk, no more processing
  if (LIKELY(error_code_ == kErrorCodeOk)) {
    return;
  }
#ifdef DEBUG
  // We output warning if some error code is not checked, but we don't do so in release mode.
  verify();
#endif  // DEBUG
  clear_custom_message();
}

Here is the call graph for this function:

Member Function Documentation

void foedus::ErrorStack::append_custom_message ( const char *  more_custom_message )

inline

Appends more custom error message at the end.

Definition at line 364 of file error_stack.hpp.

References copy_custom_message(), foedus::kErrorCodeOk, and LIKELY.

Referenced by ErrorStack().

                                                                             {
  // Invariant: if kErrorCodeOk, no more processing
  if (LIKELY(error_code_ == kErrorCodeOk)) {
    return;
  }
  // augment custom error message
  if (custom_message_) {
    // concat
    size_t cur_len = std::strlen(custom_message_);
    size_t more_len = std::strlen(more_custom_message);
    char *copied = new char[cur_len + more_len + 1];
    if (copied) {
      custom_message_ = copied;
      std::memcpy(copied, custom_message_, cur_len);
      std::memcpy(copied + cur_len, more_custom_message, more_len + 1);
    }
  } else {
    copy_custom_message(more_custom_message);  // just put the new message
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void foedus::ErrorStack::clear_custom_message ( )

inline

Deletes custom message from this object.

Definition at line 339 of file error_stack.hpp.

References CXX11_NULLPTR, and UNLIKELY.

Referenced by copy_custom_message(), and ~ErrorStack().

                                             {
  if (UNLIKELY(custom_message_)) {
    delete[] custom_message_;
    custom_message_ = CXX11_NULLPTR;
  }
}

Here is the caller graph for this function:

void foedus::ErrorStack::copy_custom_message ( const char *  message )

inline

Copy the given custom message into this object.

Definition at line 346 of file error_stack.hpp.

References clear_custom_message(), foedus::kErrorCodeOk, and LIKELY.

Referenced by append_custom_message(), and ErrorStack().

                                                               {
  // Invariant: if kErrorCodeOk, no more processing
  if (LIKELY(error_code_ == kErrorCodeOk)) {
    return;
  }

  clear_custom_message();
  if (message) {
    // do NOT use strdup to make sure new/delete everywhere.
    size_t len = std::strlen(message);
    char *copied = new char[len + 1];  // +1 for null terminator
    if (copied) {
      custom_message_ = copied;
      std::memcpy(copied, message, len + 1);
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void foedus::ErrorStack::dump_and_abort

(

const char *

abort_message

)

const

Describe this object to std::cerr and then abort.

This also leaves the dump information in static variable so that a signal handler pick it up.

Definition at line 61 of file error_stack.cpp.

References ASSERT_ND, and foedus::print_backtrace().

Referenced by verify().

                                                               {
  std::stringstream str;
  str << "foedus::ErrorStack::dump_and_abort: " << abort_message << std::endl << *this << std::endl;
  str << print_backtrace();

  static_recent_dump_and_abort += str.str();
  LOG(FATAL) << str.str();
  ASSERT_ND(false);
  std::cout.flush();
  std::cerr.flush();
  std::abort();
}

Here is the call graph for this function:

Here is the caller graph for this function:

const char * foedus::ErrorStack::get_custom_message ( ) const

inline

Returns the custom error message.

Definition at line 399 of file error_stack.hpp.

References CXX11_NULLPTR, and foedus::kErrorCodeOk.

Referenced by foedus::FixedErrorStack::from_error_stack(), foedus::FixedErrorStack::operator=(), and output().

                                                        {
  // Invariant: if kErrorCodeOk, no more processing
  if (error_code_ == kErrorCodeOk) {
    return CXX11_NULLPTR;
  }
  return custom_message_;
}

Here is the caller graph for this function:

ErrorCode foedus::ErrorStack::get_error_code ( ) const

inline

Return the integer error code.

Definition at line 390 of file error_stack.hpp.

Referenced by foedus::FixedErrorStack::from_error_stack(), and foedus::FixedErrorStack::operator=().

                                                  {
  checked_ = true;
  return error_code_;
}

Here is the caller graph for this function:

const char * foedus::ErrorStack::get_filename ( uint16_t  stack_index ) const

inline

Returns the file name of the given stack position.

Definition at line 424 of file error_stack.hpp.

References ASSERT_ND, CXX11_NULLPTR, and foedus::kErrorCodeOk.

Referenced by foedus::FixedErrorStack::from_error_stack(), foedus::FixedErrorStack::operator=(), and output().

                                                                      {
  // Invariant: if kErrorCodeOk, no more processing
  if (error_code_ == kErrorCodeOk) {
    return CXX11_NULLPTR;
  }
  ASSERT_ND(stack_index < stack_depth_);
  return filenames_[stack_index];
}

Here is the caller graph for this function:

const char * foedus::ErrorStack::get_func ( uint16_t  stack_index ) const

inline

Returns the function name of the given stack position.

Definition at line 433 of file error_stack.hpp.

References ASSERT_ND, CXX11_NULLPTR, and foedus::kErrorCodeOk.

Referenced by foedus::FixedErrorStack::from_error_stack(), foedus::FixedErrorStack::operator=(), and output().

                                                                  {
  // Invariant: if kErrorCodeOk, no more processing
  if (error_code_ == kErrorCodeOk) {
    return CXX11_NULLPTR;
  }
  ASSERT_ND(stack_index < stack_depth_);
  return funcs_[stack_index];
}

Here is the caller graph for this function:

uint32_t foedus::ErrorStack::get_linenum ( uint16_t  stack_index ) const

inline

Returns the line number of the given stack position.

Definition at line 415 of file error_stack.hpp.

References ASSERT_ND, and foedus::kErrorCodeOk.

Referenced by foedus::FixedErrorStack::from_error_stack(), foedus::FixedErrorStack::operator=(), and output().

                                                                  {
  // Invariant: if kErrorCodeOk, no more processing
  if (error_code_ == kErrorCodeOk) {
    return 0;
  }
  ASSERT_ND(stack_index < stack_depth_);
  return linenums_[stack_index];
}

Here is the caller graph for this function:

const char * foedus::ErrorStack::get_message ( ) const

inline

Returns the error message inferred by the error code.

Definition at line 395 of file error_stack.hpp.

References foedus::get_error_message().

Referenced by output().

                                                 {
  return get_error_message(error_code_);
}

Here is the call graph for this function:

Here is the caller graph for this function:

int foedus::ErrorStack::get_os_errno ( ) const

inline

Global errno of the system as of instantiation of this error stack.

Definition at line 442 of file error_stack.hpp.

References foedus::kErrorCodeOk.

Referenced by foedus::FixedErrorStack::from_error_stack(), and foedus::FixedErrorStack::operator=().

                                          {
  // Invariant: if kErrorCodeOk, no more processing
  if (error_code_ == kErrorCodeOk) {
    return 0;
  }
  return os_errno_;
}

Here is the caller graph for this function:

std::string foedus::ErrorStack::get_recent_dump_and_abort ( )

static

Signal handler can get the dump information via this.

Definition at line 74 of file error_stack.cpp.

References foedus::static_recent_dump_and_abort.

                                                {
  return static_recent_dump_and_abort;
}

uint16_t foedus::ErrorStack::get_stack_depth ( ) const

inline

Returns the depth of stack this error code has collected.

Definition at line 407 of file error_stack.hpp.

References foedus::kErrorCodeOk.

Referenced by foedus::FixedErrorStack::from_error_stack(), foedus::FixedErrorStack::operator=(), and output().

                                                  {
  // Invariant: if kErrorCodeOk, no more processing
  if (error_code_ == kErrorCodeOk) {
    return 0;
  }
  return stack_depth_;
}

Here is the caller graph for this function:

bool foedus::ErrorStack::is_error ( ) const

inline

Returns if this return code is not kErrorCodeOk.

Definition at line 385 of file error_stack.hpp.

References foedus::kErrorCodeOk.

Referenced by foedus::soc::SocManagerPimpl::child_main_common(), foedus::storage::StorageManagerPimpl::create_storage_apply(), foedus::soc::SocManagerPimpl::emulated_child_main(), foedus::soc::SocManagerPimpl::forked_child_main(), foedus::FixedErrorStack::from_error_stack(), foedus::snapshot::SnapshotManagerPimpl::glean_logs(), foedus::snapshot::SnapshotManagerPimpl::handle_snapshot(), foedus::thread::ThreadPimpl::handle_tasks(), foedus::DefaultInitializable::initialize(), foedus::soc::SocManagerPimpl::initialize_child(), foedus::soc::SocManagerPimpl::initialize_master(), foedus::EnginePimpl::initialize_once(), foedus::FixedErrorStack::operator=(), output(), foedus::ErrorStackBatch::push_back(), foedus::externalize::Externalizable::save_to_stream(), foedus::soc::SocManagerPimpl::spawned_child_main(), and foedus::UninitializeGuard::~UninitializeGuard().

                                       {
  checked_ = true;
  return error_code_ != kErrorCodeOk;
}

Here is the caller graph for this function:

ErrorStack & foedus::ErrorStack::operator= ( const ErrorStack &  other )

inline

Assignment operator.

Definition at line 302 of file error_stack.hpp.

References CXX11_NULLPTR, foedus::kErrorCodeOk, and LIKELY.

Referenced by ErrorStack().

                                                                {
  // Invariant: if kErrorCodeOk, no more processing
  if (LIKELY(other.error_code_ == kErrorCodeOk)) {
    this->error_code_ = kErrorCodeOk;
    return *this;
  }

  // this copy assignment is actually a move assignment.
  // checked_/custom_message_ are mutable for that.
  custom_message_ = other.custom_message_;  // steal.
  other.custom_message_ = CXX11_NULLPTR;  // simply stolen. much more efficient.
  stack_depth_ = other.stack_depth_;
  for (int i = 0; i < other.stack_depth_; ++i) {
    filenames_[i] = other.filenames_[i];
    funcs_[i] = other.funcs_[i];
    linenums_[i] = other.linenums_[i];
  }
  os_errno_ = other.os_errno_;
  error_code_ = other.error_code_;
  checked_ = false;
  other.checked_ = true;
  return *this;
}

Here is the caller graph for this function:

void foedus::ErrorStack::output

(

std::ostream *

ptr

)

const

Describe this object to the given stream.

Definition at line 30 of file error_stack.cpp.

References get_custom_message(), foedus::get_error_name(), get_filename(), get_func(), get_linenum(), get_message(), get_stack_depth(), is_error(), kMaxStackDepth, and foedus::assorted::os_error().

Referenced by foedus::operator<<().

                                             {
  std::ostream &o = *ptr;  // just to workaround non-const reference rule.
  if (!is_error()) {
    o << "No error";
  } else {
    o << get_error_name(error_code_) << "(" << error_code_ << "):" << get_message();
    if (os_errno_ != 0) {
      o << " (Latest system call error=" << assorted::os_error(os_errno_) << ")";
    }
    if (get_custom_message()) {
      o << " (Additional message=" << get_custom_message() << ")";
    }

    for (uint16_t stack_index = 0; stack_index < get_stack_depth(); ++stack_index) {
      o << std::endl << "  " << get_filename(stack_index)
        << ":" << get_linenum(stack_index) << ": ";
      if (get_func(stack_index) != nullptr) {
        o << get_func(stack_index) << "()";
      }
    }
    if (get_stack_depth() >= foedus::ErrorStack::kMaxStackDepth) {
      o << std::endl << "  .. and more. Increase kMaxStackDepth to see full stacktraces";
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void foedus::ErrorStack::verify ( ) const

inline

Output a warning to stderr if the error is not checked yet.

Definition at line 450 of file error_stack.hpp.

References dump_and_abort(), foedus::kErrorCodeOk, and LIKELY.

Referenced by ~ErrorStack().

                                     {
  // Invariant: if kErrorCodeOk, no more processing
  if (LIKELY(error_code_ == kErrorCodeOk)) {
    return;
  }
  if (!checked_) {
    dump_and_abort("Return value is not checked. ErrorStack must be checked");
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  o, const ErrorStack &  obj  )

friend

Definition at line 78 of file error_stack.cpp.

                                                             {
  obj.output(&o);
  return o;
}

---

The documentation for this class was generated from the following files:

• /home/shino/foedus_code/foedus-core/include/foedus/error_stack.hpp
• /home/shino/foedus_code/foedus-core/src/foedus/error_stack.cpp