%% An abstract:
%% 
%% Exception safety is a difficult topic in any language.  In non-GC'd languages
%% like C++, it can be very hard to write exception-safe code.  In Ruby, it's a
%% little easier, but there are still quite a few "gotchas".
%% 
%% The goal of this talk is to discuss some of the exception safety issues that
%% show up on the mailing list, to propose some solutions, and to discuss
%% problems not yet solved.  If time permits, exception-safety in Ruby extensions
%% written in C and C++ will also be discussed.  Some knowledge of C/C++ is
%% recommended but not required.
%% 
%% An outline:
%% 
%% I. Exception safety in Ruby
%%   A. Resource allocation/deallocation
%%      1. finalizers - hard to use, doesn't guarantee cleanup
%%      2. blocks - guaranteed cleanup, but potentially more expensive
%%   B. Exception safety guarantees
%%      1. basic guarantee - invariants preserved, no resources leaked
%%      2. strong guarantee - state remains the same if an exception is thrown
%%         a. ensure block - useful for rolling-back static operations
%%         b. undo/rollback - rollback dynamic operations in reverse order
%%            (see RubyTreasures and MetaRuby)
%%      3. no-throw guarantee - necessary when operations cannot be undone
%%   C. Intercepting exceptions (with ensure)
%%      a. re-raising the exception doesn't always work
%%      b. using ensure to intercept the exception means the exception can be
%%         propogated without being re-raised.
%%   E. Some functions must NOT raise exceptions
%%      1. freeze
%%         a. makes "deep freeze" difficult if it can raise exceptions (since
%%            "unfreeze" is impossible (note that taint/untaint are okay, since
%%            they are undoable).
%%         b. [ruby-talk:40022]
%%      2. each
%%         a. necessary for implementing freeze in some objects
%%         b. CAN pass exceptions raised in the block (since it is user code)
%%      3. <=>, ==, finalizers
%%         a. Exception will not get propogated nor printed, just ignored
%%         b. [ruby-talk:40612]
%%      4. The * operator
%%         a. Used for multiple assignment, calls to_a()
%%         b. If to_ary() fails, then * can fail, so don't use it for swap()
%%            operations.
%%   E. Error messages (reference Andrei's talk)
%%      1. Good exception message != good error message
%%      2. How to write a generic component for generating error messages?
%%   F. Exceptions in threads
%%      1. abort_on_exception - forgetting it is a common mistake
%%      2. alternative: catch exception at highest level and log it
%%   G. Errno exceptions
%%      1. Where Ruby 1.6.x returns an error code,
%%      2. Ruby 1.7.x raises an Errno::xxx exception.
%% 
%% II. Exception safety in extensions
%%   A. C - easy; C++ - hard
%%   B. First try: rb_rescue2 (doesn't work with catch/throw)
%%   C. Second try: rb_protect (how do I re-throw the symbol?)
%%      1. This technique used by Exceptional Ruby (my wrapper for writing
%%         exception-safe C++ extensions)
%%   D. Alternative: allocate everything on the heap and register it with the
%%      Ruby GC
%% 
%% III. Resources
%%   A. http://rm-f.net/~cout/ruby/treasures/RubyTreasures-0.4/lib/exc/
%%   B. http://www.gotw.ca/publications/xc++.htm
%%   C. http://www.boost.org/more/generic_exception_safety.html
%%   D. http://www.metabyte.com/~fbp/stl/eh_contract.html
%%
%% Default fonts
%deffont "standard" xfont "helvetica-medium-r", tfont "arial.ttf", tmfont "arial.ttf"
%deffont "thick" xfont "helvetica-bold-r", tfont "arialb.ttf", tmfont "arialb.ttf"
%deffont "typewriter" xfont "fixed-medium-r", tfont "cour.ttf", tmfont "cour.ttf"
%%
%% Default settings per each line number
%default 1 area 90 90, leftfill, size 2, fore "yellow", back "black", font "thick", bgrad
%default 2 size 6, vgap 10, prefix " ", ccolor "black"
%default 3 size 2, bar "gray70", vgap 10
%default 4 size 5, fore "white", vgap 30, prefix " ", font "standard"
%%
%% Default settings for tab-indented lines
%tab 1 size 5, vgap 40, prefix "  ", icon box "green" 50
%tab 2 size 4, vgap 40, prefix "      ", icon arc "yellow" 50
%tab 3 size 3, vgap 40, prefix "            ", icon delta3 "white" 40
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page
%center

Exceptional Ruby

Ruby Conference 2002

Paul Brannan
paul@atdesk.com


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Overview

	Exceptions happen
	We need to deal with them correctly
		A program shouldn't crash just because it gets an exception
		A program should never have undefined behavior
		A program should never leak resources
	GC makes the job easier, but doesn't solve it.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

A Simple Example
%%
#ruby <<END
def numberize(str, startnum=1)
  result = ''
  n = startnum
  str.each_line do |line|
    result << "#{'%2d' % n} #{line}"
    n += 1
  end
  $lastnum = n
  return result
end

def code_block(str, startnum=1)
  return <<-ENDCODEBLOCK
%font "typewriter", size 3
#{numberize(str, startnum)}
%font "standard"
  ENDCODEBLOCK
end

def simple_example
  example = <<-ENDEXAMPLE
  def read_configuration(filename)
    f = File.open(filename)
    host = f.gets
    port = f.gets.to_i
    f.close
    return host, port
  end
  ENDEXAMPLE
  return code_block(example)
end
END
%%

#{simple_example}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

One Solution

%% What happens if f.close fails?
#ruby <<END
code_block <<ENDCODEBLOCK
  def read_configuration(filename)
    f = File.open(filename)
    begin
      host = f.gets
      port = f.gets.to_i
    ensure
      f.close
    end
  end
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

The Right Way

#ruby <<END
code_block <<ENDCODEBLOCK
  def read_configuration(filename)
    File.open(filename) do |f|
      server = f.gets
      port = f.gets.to_i
      return host, port
    end
  end
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Basics of Exception Safety

	Exception Safety Guarantees (Dave Abrahams)
		basic guarantee
			invariants preserved (the object remains in a consistent state)
			no resources leaked
%pause
		strong guarantee
			state remains the same if an exception is thrown
%pause
		no-throw guarantee
			necessary for proper cleanup when exceptions are thrown
%pause
	exception-safe code meets the basic exception-safety guarantee
	exception-neutral code passes all exceptions to the caller
	purely functional code is always exception-safe

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Back to the example

#{simple_example}
	Question: Is this exception-safe?
%pause
	If an exception is raised an exception, then:
		The state is consistent
		No resources are leaked
	Answer: Yes, but...
%% (the resources are not leaked, but they are not immediately freed)

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Resource allocation/deallocation

#ruby <<END
code_block <<ENDCODEBLOCK
  # Method 1: Use finalizers (let the GC do the work)
  class Foo
    class Helper
      def initialize
        @x = allocate_some_resource
      end

      def finalize
        free_some_resource(@x)
      end
    end
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Resource allocation/deallocation (cont'd)

#ruby <<END
code = <<ENDCODEBLOCK
    def initialize
      @helper = Helper.new
      ObjectSpace.define_finalizer(
          self,
          self.class.finalizer(@helper))
    end

    def self.finalizer(helper)
      return proc { helper.finalize }
    end
  end
ENDCODEBLOCK
code_block(code, $lastnum)
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Resource allocation/deallocation (cont'd)

%% TODO: Can I find a better name for "self.with"?
#ruby <<END
code_block <<ENDCODEBLOCK
  # Method 2: Use blocks (like C++''s RAII)
  class Foo
    def initialize()
      @x = allocate_some_resource
    end

    def finalize()
      deallocate_some_resource(@x)
    end

    def self.with
      foo = Foo.new
      begin
        yield
      ensure
        foo.finalize
      end
    end
  end
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Transactions

#ruby <<END
code_block <<ENDCODEBLOCK
  require 'pstore'

  p = PStore.new('foo.db')
  p.transaction do
    p['foo'] = 42
    p['bar'] = foo()
  end
ENDCODEBLOCK
END

%pause
	Transactions allow your code to do work in memory then commit only when the work is done.
	Whenever possible, write methods that only modify state when all other work is done.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Rolling back changes

	Consider the following:

#ruby <<END
code_block <<ENDCODEBLOCK
  class UserDB
    def adduser(username, password, address, phone)
      @phone_db.adduser(username, address, phone)
      @system1_db.adduser(username, password)
      @system2_db.adduser(username, password)
    end
  end
ENDCODEBLOCK
END
	Is this exception-safe?

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Rolling back changes (cont'd)

	The snippet does not meet the strong guarantee
%pause
	Does it meet the basic guarantee?
%pause
	We need to rollback changes if any step fails

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Rolling back changes (cont'd)

	Solution:

#ruby <<END
code_block <<ENDCODEBLOCK
  class UserDB
    def adduser(username, password, address, phone)
      rollback = []
      begin
        @phone_db.adduser(username, address, phone)
        rollback.push proc { @phone_db.deluser(username) }
        @system1_db.adduser(username, password)
        rollback.push proc { @system1_db.deluser(username) }
        @system2_db.adduser(username, password)
        rollback.clear
      ensure
        rollback.reverse_each { |p| p.call }
      end
    end
  end
ENDCODEBLOCK
END

%% What would happen if deluser fails?

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

The no-throw guarantee

	Question: What happens if deluser fails?
%pause
	Question: What could we do if there were no deluser method?
%pause
	Common methods that should not throw:
		finalizers
		ensure blocks
		freeze (makes "deep freeze" difficult)

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Exception-safety in extensions

	Three problems:
		Correct behavior in presence of exceptions
		Ruby exceptions should not enter C++ code
		C++ exceptions should not enter Ruby code

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Calling C++ code from Ruby

	Can't let the C++ exception leave C++ code
		Wrap all C++ functions with try/catch blocks
		Use Swig's %except directive

%% TODO: example?

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Calling Ruby methods from C++

	Ruby exceptions and C++ exceptions don't mix
	Need to ensure that resources are not leaked
		Register everything with the GC (swig)
		Translate Ruby exceptions into C++ exceptions and back

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

An example

#ruby <<END
code_block <<ENDCODEBLOCK
  VALUE foo(VALUE self, VALUE x) {
    Foo f;
    f.foo(NUM2INT(x));
    return Qnil;
  }
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

A generic solution

#ruby <<END
code_block <<ENDCODEBLOCK
  struct Ruby_Jump_Tag {
    Ruby_Jump_Tag(int t) : tag(t) { }
    int tag;
  };
  
  struct Ruby_Exception {
    Ruby_Exception(VALUE e) : ex(e) { }
    VALUE ex;
  }
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

A generic solution (cont'd)

#ruby <<END
code_block <<ENDCODEBLOCK
  typedef VALUE (*RUBY_VALUE_FUNC)(VALUE);
  VALUE rb_cpp_protect(RUBY_VALUE_FUNC f, VALUE arg) {
    int state = 0;
    VALUE retval = rb_protect(f, arg, &state);
    if(state != 0) {
      throw Ruby_Jump_Tag(state);
    }
  }
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

A generic solution (cont'd)

#ruby <<END
code_block <<ENDCODEBLOCK
  #define RUBY_TRY \\ 
    int ruby_jump_tag = 0; \\ 
    VALUE ruby_exc = Qnil; \\ 
    goto start_of_RUBY_TRY; \\ 
    ruby_exception: rb_exc_raise(ruby_exc); \\ 
    ruby_jump_tag: rb_jump_tag(ruby_jump_tag); \\ 
    start_of_RUBY_TRY: \\ 
    try
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

A generic solution (cont'd)

#ruby <<END
code_block <<ENDCODEBLOCK
  #define RUBY_CATCH \\ 
    catch(Ruby_Jump_Tag const & ex) { \\ 
      ruby_jump_tag = ex.tag; \\ 
      goto ruby_jump_tag;  \\ 
    } \\ 
    catch(...) { \\ 
      RUBY_RETHROW(rb_exc_new2( \\ 
          rb_eRuntimeError, \\ 
          "unknown C++ exception thrown")); \\ 
    }
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

A generic solution (cont'd)

#ruby <<END
code_block <<ENDCODEBLOCK
  #define RUBY_RETHROW(ex) \\ 
    ruby_exc = ex; \\ 
    goto ruby_exception;
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

A generic solution (cont'd)

#ruby <<END
code_block <<ENDCODEBLOCK
  VALUE rb_cpp_num2long(VALUE x) {
    return (VALUE)(NUM2LONG(x));
  }

  unsigned long CPP_NUM2INT(VALUE x)
  {
    return (unsigned long)(rb_cpp_protect(
        Conversion_Helpers::rb_cpp_num2ulong, x));
  }
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

A generic solution (cont'd)

#ruby <<END
code_block <<ENDCODEBLOCK
  VALUE foo(VALUE self, VALUE x) {
    RUBY_TRY {
      Foo f;
      f.foo(CPP_NUM2INT(x));
      return Qnil;
    } catch(std::bad_alloc & ex) {
      RUBY_RETHROW(rb_exc_new2(
          rb_eRuntimeError,
          "failed to allocate memory"));
    } RUBY_CATCH
  }
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Exceptions with Swig

#ruby <<END
code_block <<ENDCODEBLOCK
  void foo(int x);

  %except(ruby) {
    RUBY_TRY {
      $function
    } catch(std::bad_alloc & ex) {
      RUBY_RETHROW(rb_exc_new2(
          rb_eRuntimeError,
          "failed to allocate memory"));
    } RUBY_CATCH
  }
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Is this code exception-safe?

#ruby <<END
code_block <<ENDCODEBLOCK
  class Foo
    def initialize
      @x = Bar.new
      @y = 10
      @z = 20
    end

    def foo
      x = @x
      @x = @y, @z
      @y, @z = x
    end
  end
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Answer: probably

#ruby <<END
code_block <<ENDCODEBLOCK
  class Bar
    def to_ary
      raise "uh oh!"
    end
  end

  f = Foo.new
  begin; f.foo; rescue; end
ENDCODEBLOCK
END

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Summary

	Exceptions are hiding everywhere in Ruby
	Writing code that works correctly in the presence of exceptions is not easy, but is possible
	Some important guidelines:
		Use ensure blocks whenever possible
		Don't allow ensure blocks to raise new exceptions
		Write methods that only modify state when all other work is done.
	Exception-safety is not without overhead
	Exception-safety in extensions can be partly solved by translating exceptions

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%page

Resources

%size 4
%icon box "green" 50
Exceptional C++ by Herb Sutter
%icon box "green" 50
http://www.gotw.ca/publications/xc++.htm
%icon box "green" 50
http://www.boost.org/more/generic_exception_safety.html
%icon box "green" 50
http://www.metabyte.com/~fbp/stl/eh_contract.html
%icon box "green" 50
http://rm-f.net/~cout/code/ruby/treasures/RubyTreasures-0.4/lib/exc/