sedna 0.3.0 → 0.4.0

data/CHANGES

@@ -1,3 +1,21 @@
+=== 0.4.0
+
+* Released on January 4th, 2009.
+* Added Sedna#reset, which closes the current connection and reconnects.
+* Added Sedna#connected?, which returns whether or not the current connection
+  is still active.
+* Sedna#transaction can now also be used without a block. Use the newly added
+  methods Sedna#commit and Sedna#rollback to finish such a declarative
+  transaction. Note that this style is not recommended if a transaction can
+  be wrapped in a block.
+* Sedna.connect no longer blocks other threads in Ruby 1.9.1+. Use Sedna.blocking?
+  to discover if support for non-blocking behaviour is enabled.
+* Strings in the result Array of Sedna#execute are now in UTF-8 encoding in
+  Ruby 1.9, rather than binary.
+* Fully tested in Ruby 1.8.5+ (including the latest version, 1.9.1 RC1).
+* Now also compiles with Ruby 1.9.0.x, but non-blocking behaviour is disabled
+  for these versions.
+
 === 0.3.0
 
 * Released on December 21st, 2008.

data/README

@@ -16,7 +16,7 @@ at http://modis.ispras.ru/sedna
 
 Author: Rolf Timmermans (r.timmermans <i>at</i> voormedia.com)
 
-Copyright 2008 Voormedia B.V.
+Copyright 2008, 2009 Voormedia B.V.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -32,9 +32,8 @@ limitations under the License.
 
 === Current version
 
-The current version of this library is 0.3.0. This release is a <b>beta version</b>.
-The API may change significantly between minor versions. For a complete overview
-all recent and previous changes, see CHANGES.
+The current version of this library is 0.4.0. This release is a <b>beta version</b>.
+For a complete overview all recent and previous changes, see CHANGES.
 
 === Requirements
 
@@ -43,8 +42,7 @@ header files of the C driver. They are shipped and installed as part of the bina
 distribution of \Sedna. When installing, choose either <tt>/usr/local/sedna</tt> or
 <tt>/opt/sedna</tt> as target locations.
 
-The library has been tested with Ruby 1.8.5 and above, including Ruby 1.9.1
-(preview 2), but excluding Ruby 1.9.0.
+The library has been tested with Ruby 1.8.5 and above, including Ruby 1.9.
 
 === Installation
 
@@ -69,7 +67,8 @@ using it.
 
 To start querying a database, create a new connection with the Sedna.connect
 method. When a block is given, the Sedna connection object will be returned
-which can be used to execute database statements.
+which can be used to execute database statements. See the documentation of the
+Sedna class for more details.
 
   connection_details = {
     :database => "my_db",
@@ -77,13 +76,36 @@ which can be used to execute database statements.
     :username => "SYSTEM",
     :password => "MANAGER",
   }
-  Sedna.connect(connection_details) do |sedna|
+
+  Sedna.connect connection_details do |sedna|
     # Start querying the database.
-    sedna.execute("create document 'mydoc'")                                  #=> nil
-    sedna.execute("update insert <msg>Hello world!</msg> into doc('mydoc')")  #=> nil
-    sedna.execute("doc('mydoc')/msg/text()")                                  #=> ["Hello world!"]
+    sedna.execute "create document 'my_doc'"                                  #=> nil
+    sedna.execute "update insert <msg>Hello world!</msg> into doc('my_doc')"  #=> nil
+    sedna.execute "doc('my_doc')/msg/text()"                                  #=> ["Hello world!"]
     # The connection is closed automatically for us.
   end
 
-See the documentation of the Sedna class -- the methods Sedna.connect and
-Sedna#execute in particular -- for more details.
+Use Sedna#load_document to load a document into the database from a string or
+file.
+
+  sedna.load_document "<msg>Hello world!</msg>", "my_doc", "my_collection"
+  sedna.execute "doc('my_doc', 'my_collection')/msg/text()"                   #=> ["Hello world!"]
+
+  File.open "document.xml" do |file|
+    sedna.load_document file, "my_doc2", "my_collection"
+  end
+  
+Use Sedna#transaction to wrap multiple database statements in a transaction.
+This ensures that either all or none of these statements are executed. If
+something goes wrong halfway, the previously executed statements that are part
+of the transaction will be rolled back.
+
+  sedna.transaction do
+    amount = 100
+    sedna.execute "update replace $balance in doc('my_account')/balance
+                   with <balance>{$balance - #{amount}}</balance>"
+    sedna.execute "update replace $balance in doc('your_account')/balance
+                   with <balance>{$balance + #{amount}}</balance>"
+    # If the second statement fails, the first will be rolled back. Only if
+    # both statements succeed will the changes become permanent.
+  end

data/Rakefile

@@ -1,4 +1,4 @@
-# Copyright 2008 Voormedia B.V.
+# Copyright 2008, 2009 Voormedia B.V.
 # 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -30,7 +30,7 @@ RDOC_FILES = FileList["[A-Z][A-Z]*", "ext/**/*.c"].to_a
 task :default => [:rebuild, :test]
 
 task :multi do
-  exec "export EXCLUDED_VERSIONS=v1_9_0 && multiruby -S rake"
+  exec "multiruby -S rake"
 end
 
 desc "Build the Ruby extension"
@@ -57,7 +57,7 @@ end
 
 gem_spec = Gem::Specification.new do |s|
   s.name = "sedna"
-  s.version = "0.3.0"
+  s.version = "0.4.0"
 
   s.summary = "Sedna XML DBMS client library."
   s.description = %{Ruby extension that provides a client library for the Sedna XML DBMS, making use of the official C driver of the Sedna project.}

data/ext/extconf.rb

@@ -1,4 +1,4 @@
-# Copyright 2008 Voormedia B.V.
+# Copyright 2008, 2009 Voormedia B.V.
 # 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -68,13 +68,8 @@ passing the -fPIC option to gcc.
   end
 end
 
-if have_func("rb_thread_blocking_region") and !have_func("rb_mutex_synchronize")
-  $stderr.write %{==============================================================================
-This Ruby version incorrectly defines Mutex#synchronize. Please upgrade to a
-newer version of Ruby (1.9.1+).
-==============================================================================
-}
-  exit 5
-end
+have_func "rb_thread_blocking_region"
+have_func "rb_mutex_synchronize"
+have_func "rb_enc_str_buf_cat"
 
 create_makefile "sedna"

data/ext/sedna.c

@@ -1,5 +1,5 @@
 /*
- * Copyright 2008 Voormedia B.V.
+ * Copyright 2008, 2009 Voormedia B.V.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -49,31 +49,73 @@
 #define PROTO_TO_STRING(s) PROTO_STRINGIFY(s)
 #define PROTOCOL_VERSION PROTO_TO_STRING(SE_CURRENT_SOCKET_PROTOCOL_VERSION_MAJOR) "." PROTO_TO_STRING(SE_CURRENT_SOCKET_PROTOCOL_VERSION_MINOR)
 
-// Default connection arguments
+// Default connection arguments.
 #define DEFAULT_HOST "localhost"
-#define DEFAULT_DATABASE "test"
+#define DEFAULT_DB "test"
 #define DEFAULT_USER "SYSTEM"
-#define DEFAULT_PASSWORD "MANAGER"
+#define DEFAULT_PW "MANAGER"
+
+// Instance variable names.
+#define IV_HOST "@host"
+#define IV_DB "@database"
+#define IV_USER "@username"
+#define IV_PW "@password"
+#define IV_AUTOCOMMIT "@autocommit"
+#define IV_MUTEX "@mutex"
 
 // Define a shorthand for the common SednaConnection structure.
 typedef struct SednaConnection SC;
 
-#ifdef HAVE_RB_THREAD_BLOCKING_REGION
-	#define NON_BLOCKING
-	#define SEDNA_BLOCKING Qfalse
+// Define a struct for database queries.
+struct SednaQuery {
+	void *conn;
+	void *query;
+};
+typedef struct SednaQuery SQ;
+
+// Define a struct for database connection arguments.
+struct SednaConnArgs {
+	void *conn;
+	void *host;
+	void *db;
+	void *user;
+	void *pw;
+};
+typedef struct SednaConnArgs SCA;
+
+// Always create UTF-8 strings with STR_CAT, if supported (Ruby 1.9).
+#ifdef HAVE_RB_ENC_STR_BUF_CAT
+	#ifndef RUBY_ENCODING_H
+		#include "ruby/encoding.h"
+	#endif
+	#define STR_CAT(str, buf, bytes) rb_enc_str_buf_cat(str, buf, bytes, rb_utf8_encoding())
+#else
+	#define STR_CAT(str, buf, bytes) rb_str_buf_cat(str, buf, bytes)
+#endif
 
-	struct SednaQuery {
-		void *conn;
-		void *query;
-	};
-	typedef struct SednaQuery SQ;
+// Define whether or not non-blocking behaviour will be built in.
+#if defined(HAVE_RB_THREAD_BLOCKING_REGION) && defined(HAVE_RB_MUTEX_SYNCHRONIZE)
+	#define NON_BLOCKING 1
+	#define SEDNA_BLOCKING Qfalse
 #else
 	#define SEDNA_BLOCKING Qtrue
 #endif
 
+// Define execute and connect functions.
+#ifdef NON_BLOCKING
+	// Non-blocking variants for >= 1.9.
+	// Synchronize across threads using this instance and execute.
+	#define SEDNA_CONNECT(self, c) rb_mutex_synchronize(rb_iv_get(self, IV_MUTEX), (void*)sedna_non_blocking_connect, (VALUE)c);
+	#define SEDNA_EXECUTE(self, q) rb_mutex_synchronize(rb_iv_get(self, IV_MUTEX), (void*)sedna_non_blocking_execute, (VALUE)q);
+#else
+	// Blocking variants for < 1.9.
+	#define SEDNA_CONNECT(self, c) sedna_blocking_connect(c);
+	#define SEDNA_EXECUTE(self, q) sedna_blocking_execute(q);
+#endif
+
 // Ruby classes.
 static VALUE cSedna;
-//static VALUE cSednaSet; //Unused so far.
+//static VALUE cSednaSet; // Stick to Array for result sets.
 static VALUE cSednaException;
 static VALUE cSednaAuthError;
 static VALUE cSednaConnError;
@@ -146,18 +188,44 @@ static void sedna_free(SC *conn)
 static void sedna_mark(SC *conn)
 { /* Unused. */ }
 
-#ifdef NON_BLOCKING
-static int sedna_blocking_execute(SQ *q)
+// Connect to the server.
+static int sedna_blocking_connect(SCA *c)
 {
-	return SEexecute(q->conn, q->query);
+	return SEconnect(c->conn, c->host, c->db, c->user, c->pw);
 }
 
-static int sedna_execute(SQ *q)
+#ifdef NON_BLOCKING
+static int sedna_non_blocking_connect(SCA *c)
 {
-	return rb_thread_blocking_region((void*)sedna_blocking_execute, q, RUBY_UBF_IO, NULL);
+	return rb_thread_blocking_region((void*)sedna_blocking_connect, c, RUBY_UBF_IO, NULL);
 }
 #endif
 
+static void sedna_connect(VALUE self, SCA *c)
+{
+	int res = SEDNA_CONNECT(self, c);
+	if(res != SEDNA_SESSION_OPEN) {
+		// We have to set the connection status to closed explicitly here,
+		// because the GC routine sedna_free() will test for this status, but
+		// the socket is already closed by SEconnect(). If we do not change the
+		// status, sedna_free() will attempt to close the connection again by
+		// calling SEclose(), which will definitely lead to unpredictable
+		// results.
+		((SC*)c->conn)->isConnectionOk = SEDNA_CONNECTION_CLOSED;
+		sedna_err(c->conn, res);
+	}
+}
+
+// Close the connection to the server.
+static void sedna_close(SC *conn)
+{
+	int res;
+	if(SEconnectionStatus(conn) != SEDNA_CONNECTION_CLOSED) {
+		res = SEclose(conn);
+		VERIFY_RES(SEDNA_SESSION_CLOSED, res, conn);
+	}
+}
+
 // Read one record completely and return it as a Ruby String object.
 static VALUE sedna_read(SC *conn, int strip_n)
 {
@@ -177,11 +245,11 @@ static VALUE sedna_read(SC *conn, int strip_n)
 					// except the first. Strip them! This a known issue in the
 					// network protocol and serialization mechanism.
 					// See: http://sourceforge.net/mailarchive/forum.php?thread_name=3034886f0812030132v3bbd8e2erd86480d3dc640664%40mail.gmail.com&forum_name=sedna-discussion
-					rb_str_buf_cat(str, buffer + 1, bytes_read - 1);
+					STR_CAT(str, buffer + 1, bytes_read - 1);
 					// Do not strip newlines from subsequent buffer reads.
 					strip_n = 0;
 				} else {
-					rb_str_buf_cat(str, buffer, bytes_read);
+					STR_CAT(str, buffer, bytes_read);
 				}
 			}
 		}
@@ -194,6 +262,7 @@ static VALUE sedna_read(SC *conn, int strip_n)
 static VALUE sedna_get_results(SC *conn)
 {
 	int res, strip_n = 0;
+	// Can be replaced with: rb_funcall(cSednaSet, rb_intern("new"), 0, NULL);
 	VALUE set = rb_ary_new();
 
 	while((res = SEnext(conn)) != SEDNA_RESULT_END) {
@@ -207,6 +276,18 @@ static VALUE sedna_get_results(SC *conn)
 	return set;
 }
 
+static int sedna_blocking_execute(SQ *q)
+{
+	return SEexecute(q->conn, q->query);
+}
+
+#ifdef NON_BLOCKING
+static int sedna_non_blocking_execute(SQ *q)
+{
+	return rb_thread_blocking_region((void*)sedna_blocking_execute, q, RUBY_UBF_IO, NULL);
+}
+#endif
+
 // Enable or disable autocommit.
 static void sedna_autocommit(SC *conn, int value)
 {
@@ -215,24 +296,73 @@ static void sedna_autocommit(SC *conn, int value)
 }
 
 // Begin a transaction.
-static void sedna_tr_begin(SC *conn)
+static void sedna_begin(SC *conn)
 {
-	int res = SEbegin(conn);
+	int res;
+
+	// Disable autocommit mode.
+	SEDNA_AUTOCOMMIT_DISABLE(conn);
+	
+	// Start the transaction.
+	res = SEbegin(conn);
 	VERIFY_RES(SEDNA_BEGIN_TRANSACTION_SUCCEEDED, res, conn);
 }
 
 // Commit a transaction.
 static void sedna_tr_commit(SC *conn)
 {
-	int res = SEcommit(conn);
-	VERIFY_RES(SEDNA_COMMIT_TRANSACTION_SUCCEEDED, res, conn);
+	int res;
+
+	if(SEtransactionStatus(conn) == SEDNA_TRANSACTION_ACTIVE) {
+		// Commit if a transaction was in progres.
+		res = SEcommit(conn);
+		VERIFY_RES(SEDNA_COMMIT_TRANSACTION_SUCCEEDED, res, conn);
+	} else {
+		// If there is no current transaction, raise an error.
+		rb_raise(cSednaTrnError, "No transaction in progress, cannot commit.");
+	}
+}
+
+// Commit a transaction and reset autocommit mode.
+static void sedna_commit(SC *conn, VALUE self)
+{
+	int status;
+
+	// Roll back.
+	rb_protect((void*)sedna_tr_commit, (VALUE)conn, &status);
+
+	// Turn autocommit back on if it was set.
+	SWITCH_SEDNA_AUTOCOMMIT(conn, rb_iv_get(self, IV_AUTOCOMMIT));
+
+	// Re-raise any exception.
+	if(status != 0) rb_jump_tag(status);
 }
 
 // Rollback a transaction.
 static void sedna_tr_rollback(SC *conn)
 {
-	int res = SErollback(conn);
-	VERIFY_RES(SEDNA_ROLLBACK_TRANSACTION_SUCCEEDED, res, conn);
+	int res;
+	
+	// Roll back if a transaction was in progress.
+	if(SEtransactionStatus(conn) == SEDNA_TRANSACTION_ACTIVE) {
+		res = SErollback(conn);
+		VERIFY_RES(SEDNA_ROLLBACK_TRANSACTION_SUCCEEDED, res, conn);
+	}
+}
+
+// Rollback a transaction and reset autocommit mode.
+static void sedna_rollback(SC *conn, VALUE self)
+{
+	int status;
+
+	// Roll back.
+	rb_protect((void*)sedna_tr_rollback, (VALUE)conn, &status);
+
+	// Turn autocommit back on if it was set.
+	SWITCH_SEDNA_AUTOCOMMIT(conn, rb_iv_get(self, IV_AUTOCOMMIT));
+
+	// Re-raise any exception.
+	if(status != 0) rb_jump_tag(status);
 }
 
 
@@ -251,45 +381,47 @@ static VALUE cSedna_s_new(VALUE klass)
 
 /* :nodoc:
  *
- * Initialize a new instance of Sedna.
+ * Initialize a new instance of Sedna. Undocumented, because Sedna.connect should
+ * be used instead.
  */
 static VALUE cSedna_initialize(VALUE self, VALUE options)
 {
-	int res;
 	VALUE host_k, db_k, user_k, pw_k, host_v, db_v, user_v, pw_v;
 	char *host, *db, *user, *pw;
-	SC *conn = sedna_struct(self);
 
+	// Ensure the argument is a Hash.
 	Check_Type(options, T_HASH);
+	
+	// Store the symbols of the valid hash keys.
 	host_k = ID2SYM(rb_intern("host"));
 	db_k = ID2SYM(rb_intern("database"));
 	user_k = ID2SYM(rb_intern("username"));
 	pw_k = ID2SYM(rb_intern("password"));
 
+	// Get the connection details or set them to the default values if not given.
 	if(NIL_P(host_v = rb_hash_aref(options, host_k))) host = DEFAULT_HOST; else host = STR2CSTR(host_v);
-	if(NIL_P(db_v = rb_hash_aref(options, db_k))) db = DEFAULT_DATABASE; else db = STR2CSTR(db_v);
+	if(NIL_P(db_v = rb_hash_aref(options, db_k))) db = DEFAULT_DB; else db = STR2CSTR(db_v);
 	if(NIL_P(user_v = rb_hash_aref(options, user_k))) user = DEFAULT_USER; else user = STR2CSTR(user_v);
-	if(NIL_P(pw_v = rb_hash_aref(options, pw_k))) pw = DEFAULT_PASSWORD; else pw = STR2CSTR(pw_v);
-
-	res = SEconnect(conn, host, db, user, pw);
-	if(res != SEDNA_SESSION_OPEN) {
-		// We have to set the connection status to closed explicitly here,
-		// because the GC routine sedna_free() will test for this status, but
-		// the socket is already closed by SEconnect(). If we do not change the
-		// status, sedna_free() will attempt to close the connection again by
-		// calling SEclose(), which will definitely lead to unpredictable
-		// results.
-		conn->isConnectionOk = SEDNA_CONNECTION_CLOSED;
-		sedna_err(conn, res);
-	}
-
-	// Initialize @autocommit to true (default argument).
-	rb_iv_set(self, "@autocommit", Qtrue);
+	if(NIL_P(pw_v = rb_hash_aref(options, pw_k))) pw = DEFAULT_PW; else pw = STR2CSTR(pw_v);
+	
+	// Save all connection details to instance variables.
+	rb_iv_set(self, IV_HOST, rb_str_new2(host));
+	rb_iv_set(self, IV_DB, rb_str_new2(db));
+	rb_iv_set(self, IV_USER, rb_str_new2(user));
+	rb_iv_set(self, IV_PW, rb_str_new2(pw));
 
 #ifdef NON_BLOCKING
-	rb_iv_set(self, "@mutex", rb_mutex_new());
+	// Create a mutex if this build supports non-blocking queries.
+	rb_iv_set(self, IV_MUTEX, rb_mutex_new());
 #endif
 
+	// Connect to the database.
+	SCA c = { sedna_struct(self), host, db, user, pw };
+	sedna_connect(self, &c);
+
+	// Initialize @autocommit to true.
+	rb_iv_set(self, IV_AUTOCOMMIT, Qtrue);
+
 	return self;
 }
 
@@ -297,20 +429,48 @@ static VALUE cSedna_initialize(VALUE self, VALUE options)
  * call-seq:
  *   sedna.close -> nil
  *
- * Closes an open Sedna connection. If the connection was already closed when
+ * Closes an open Sedna connection. If the connection is already closed when
  * this method is called, nothing happens. A Sedna::ConnectionError is raised
  * if the connection was open but could not be closed.
  */
 static VALUE cSedna_close(VALUE self)
 {
-	int res;
 	SC *conn = sedna_struct(self);
+	
+	// Ensure the connection is closed.
+	sedna_close(conn);
+	
+	// Always return nil if successful.
+	return Qnil;
+}
+
+/*
+ * call-seq:
+ *   sedna.reset -> nil
+ *
+ * Closes an open Sedna connection and reconnects. If the connection is already
+ * closed when this method is called, the connection is just reestablished. When
+ * reconnecting, the same connection details are used that were given when initially
+ * connecting with the connect method.
+ *
+ * If the connection could not be closed or reopened, a Sedna::ConnectionError is
+ * raised. If the authentication fails when reconnecting, a
+ * Sedna::AuthenticationError is raised.
+ */
+static VALUE cSedna_reset(VALUE self)
+{
+	SC *conn = sedna_struct(self);
+	
+	// First ensure the current connection is closed.
+	sedna_close(conn);
 
-	if(SEconnectionStatus(conn) != SEDNA_CONNECTION_CLOSED) {
-		res = SEclose(conn);
-		VERIFY_RES(SEDNA_SESSION_CLOSED, res, conn);
-	}
+	// Retrieve stored connection details.
+	SCA c = { conn, STR2CSTR(rb_iv_get(self, IV_HOST)), STR2CSTR(rb_iv_get(self, IV_DB)), STR2CSTR(rb_iv_get(self, IV_USER)), STR2CSTR(rb_iv_get(self, IV_PW)) };
+	
+	// Connect to the database.
+	sedna_connect(self, &c);
 
+	// Always return nil if successful.
 	return Qnil;
 }
 
@@ -320,32 +480,40 @@ static VALUE cSedna_close(VALUE self)
  *   Sedna.connect(details) {|sedna| ... } -> nil
  *
  * Establishes a new connection to a \Sedna XML database. Accepts a hash that
- * describes which database to \connect to.
+ * describes which database to connect to.
  *
  * If a block is given, the block is executed if a connection was successfully
- * established. The connection is closed at the end of the block. If called
+ * established. The connection is closed at the end of the block or if the
+ * stack is unwinded (if an exception is raised, for example). If called
  * without a block, a Sedna object that represents the connection is returned.
  * The connection should be closed by calling Sedna#close.
  *
  * If a connection cannot be initiated, a Sedna::ConnectionError is raised.
  * If the authentication fails, a Sedna::AuthenticationError is raised.
  *
+ * This method does not block other threads in Ruby 1.9.1+ -- connections that
+ * are initiated in different threads will be created concurrently. You can
+ * use Sedna.blocking? to verify if the extension supports non-blocking
+ * behaviour.
+ *
  * ==== Valid connection details keys
  *
- * * <tt>:host</tt> - Host name or IP address to which to \connect to (defaults to +localhost+).
- * * <tt>:database</tt> - Name of the database to \connect to (defaults to +test+).
+ * * <tt>:host</tt> - Host name or IP address to which to connect to (defaults to +localhost+).
+ * * <tt>:database</tt> - Name of the database to connect to (defaults to +test+).
  * * <tt>:username</tt> - User name to authenticate with (defaults to +SYSTEM+).
  * * <tt>:password</tt> - Password to authenticate with (defaults to +MANAGER+).
  *
  * ==== Examples
  *
  * Call without a block and close the connection afterwards.
- *   sedna = Sedna.connect(:database => "my_db", :host => "my_host")
+ *
+ *   sedna = Sedna.connect :database => "my_db", :host => "my_host"
  *   # Query the database and close afterwards.
  *   sedna.close
  *
  * Call with a block. The connection is closed automatically.
- *   Sedna.connect(:database => "my_db", :host => "my_host") do |sedna|
+ *
+ *   Sedna.connect :database => "my_db", :host => "my_host" do |sedna|
  *     # Query the database.
  *     # The connection is closed automatically.
  *   end
@@ -353,15 +521,24 @@ static VALUE cSedna_close(VALUE self)
 static VALUE cSedna_s_connect(VALUE klass, VALUE options)
 {
 	int status;
+	
+	// Create a new instance.
 	VALUE obj = rb_funcall(klass, rb_intern("new"), 1, options);
 
 	if(rb_block_given_p()) {
+		// If a block is given, yield the instance, and make sure we always return...
 		rb_protect(rb_yield, obj, &status);
+		
+		// ...to ensure that the connection is closed afterwards.
 		cSedna_close(obj);
-		if(status != 0) rb_jump_tag(status); // Re-raise any exception.
+		
+		// Re-raise any exception.
+		if(status != 0) rb_jump_tag(status);
 
+		// Always return nil if successful.
 		return Qnil;
 	} else {
+		// If no block is given, simply return the instance.
 		return obj;
 	}
 }
@@ -381,16 +558,33 @@ static VALUE cSedna_s_version(VALUE klass)
  * call-seq:
  *   Sedna.blocking? -> true or false
  *
- * Returns +true+ if querying the database with Sedna#execute will block other
- * threads. Returns +false+ if multiple queries can be run in different threads
- * simultaneously. \Sedna will not block other threads when compiled against
- * Ruby 1.9.
+ * Returns +true+ if connecting with Sedna.connect or querying the database
+ * with Sedna#execute will block other threads. Returns +false+ if multiple
+ * queries can be run or multiple connections can be made simultaneously in
+ * different threads. \Sedna will not block other threads (this method returns
+ * +false+) when compiled against Ruby 1.9.1+.
  */
 static VALUE cSedna_s_blocking(VALUE klass)
 {
 	return SEDNA_BLOCKING;
 }
 
+/*
+ * call-seq:
+ *   sedna.connected? -> true or false
+ *
+ * Returns +true+ if the connection is connected and functioning properly. Returns
+ * +false+ if the connection has been closed.
+ */
+static VALUE cSedna_connected(VALUE self)
+{
+	SC *conn = sedna_struct(self);
+	
+	// Return true if the connection status is OK. This only indicates that the
+	// client still thinks it is connected.
+	return (SEconnectionStatus(conn) == SEDNA_CONNECTION_OK) ? Qtrue : Qfalse;
+}
+
 /*
  * call-seq:
  *   sedna.execute(query) -> array or nil
@@ -399,11 +593,11 @@ static VALUE cSedna_s_blocking(VALUE klass)
  * Executes the given +query+ against a \Sedna database. Returns an array if the
  * given query is a select query. The elements of the array are strings that
  * correspond to each result in the result set. If the query is an update query
- * or a (bulk) load query, +nil+ is returned. When attempting to \execute a
+ * or a (bulk) load query, +nil+ is returned. When attempting to execute a
  * query on a closed connection, a Sedna::ConnectionError will be raised. A
  * Sedna::Exception is raised if the query fails or is invalid.
  *
- * This method does not block other threads in Ruby 1.9 -- database queries that
+ * This method does not block other threads in Ruby 1.9.1+ -- database queries that
  * are run in different threads with different connections will run concurrently.
  * You can use Sedna.blocking? to verify if the extension supports non-blocking
  * behaviour. Database queries run from different threads, but on the same
@@ -412,12 +606,17 @@ static VALUE cSedna_s_blocking(VALUE klass)
  * ==== Examples
  *
  * Create a new document.
+ *
  *   sedna.execute "create document 'mydoc'"
  *     #=> nil
+ *
  * Update the newly created document with a root node.
+ *
  *   sedna.execute "update insert <message>Hello world!</message> into doc('mydoc')"
  *     #=> nil
+ *
  * Select a node in a document using XPath.
+ *
  *   sedna.execute "doc('mydoc')/message/text()"
  *     #=> ["Hello world!"]
  *
@@ -429,27 +628,27 @@ static VALUE cSedna_s_blocking(VALUE klass)
  */
 static VALUE cSedna_execute(VALUE self, VALUE query)
 {
-	int res;
 	SC *conn = sedna_struct(self);
 
-	if(SEconnectionStatus(conn) != SEDNA_CONNECTION_OK) rb_raise(cSednaConnError, "Connection is closed.");
-
-#ifdef NON_BLOCKING
-	// Non-blocking variant for >= 1.9.
+	// Prepare query arguments.
 	SQ q = { conn, STR2CSTR(query) };
-	res = rb_mutex_synchronize(rb_iv_get(self, "@mutex"), (void*)sedna_execute, (VALUE)&q);
-#else
-	// Blocking variant for < 1.9.
-	res = SEexecute(conn, STR2CSTR(query));
-#endif
+
+	// Verify that the connection is OK.
+	if(SEconnectionStatus(conn) != SEDNA_CONNECTION_OK) rb_raise(cSednaConnError, "Connection is closed.");
+	
+	// Execute query.
+	int res = SEDNA_EXECUTE(self, &q);
 
 	switch(res) {
 		case SEDNA_QUERY_SUCCEEDED:
+			// Return the results if this was a query.
 			return sedna_get_results(conn);
 		case SEDNA_UPDATE_SUCCEEDED:
 		case SEDNA_BULK_LOAD_SUCCEEDED:
+			// Return nil if this was an update or bulk load.
 			return Qnil;
 		default:
+			// Raise an exception if something else happened.
 			sedna_err(conn, res);
 			return Qnil;
 	}
@@ -470,7 +669,7 @@ static VALUE cSedna_execute(VALUE self, VALUE query)
  *
  * ==== Examples
  *
- * Create a new standalone document and retrieve it.
+ * Create a new document and retrieve its contents.
  *
  *   sedna.load_document "<my_document>Hello world!</my_document>", "my_doc"       
  *     #=> nil
@@ -490,29 +689,41 @@ static VALUE cSedna_load_document(int argc, VALUE *argv, VALUE self)
 	VALUE document, doc_name, col_name, buf;
 	char *doc_name_c, *col_name_c;
 
+	// Verify that the connection is OK.
 	if(SEconnectionStatus(conn) != SEDNA_CONNECTION_OK) rb_raise(cSednaConnError, "Connection is closed.");
 
-	rb_scan_args(argc, argv, "21", &document, &doc_name, &col_name); // 2 mandatory args, 1 optional.
+	// 2 mandatory arguments, 1 optional.
+	rb_scan_args(argc, argv, "21", &document, &doc_name, &col_name);
 	doc_name_c = STR2CSTR(doc_name);
 	col_name_c = NIL_P(col_name) ? NULL : STR2CSTR(col_name);
 
 	if(TYPE(document) == T_FILE) {
+		// If the document is an IO object...
 		while(!NIL_P(buf = rb_funcall(document, rb_intern("read"), 1, INT2NUM(LOAD_BUF_LEN)))) {
+			// ...read from it until we reach EOF and load the data.
 			res = SEloadData(conn, STR2CSTR(buf), RSTRING_LEN(buf), doc_name_c, col_name_c);
 			VERIFY_RES(SEDNA_DATA_CHUNK_LOADED, res, conn);
 		}
+
+		// If there is no data, raise an exception.
 		if(res == 0) rb_raise(cSednaException, "Document is empty.");
 	} else {
+		// If the document is not an IO object, verify it is a string instead.
 		Check_Type(document, T_STRING);
+		
+		// If there is no data, raise an exception.
 		if(RSTRING_LEN(document) == 0) rb_raise(cSednaException, "Document is empty.");
 
+		// Load the data.
 		res = SEloadData(conn, STR2CSTR(document), RSTRING_LEN(document), doc_name_c, col_name_c);
 		VERIFY_RES(SEDNA_DATA_CHUNK_LOADED, res, conn);
 	}
 
+	// Signal that we're finished.
 	res = SEendLoadData(conn);
 	VERIFY_RES(SEDNA_BULK_LOAD_SUCCEEDED, res, conn);
 
+	// Always return nil if successful.
 	return Qnil;
 }
 
@@ -525,9 +736,13 @@ static VALUE cSedna_autocommit_set(VALUE self, VALUE auto_commit)
 	int val = (RTEST(auto_commit) ? Qtrue : Qfalse);
 	SC *conn = sedna_struct(self);
 
+	// Switch autocommit mode on or off.
 	SWITCH_SEDNA_AUTOCOMMIT(conn, val);
-	rb_iv_set(self, "@autocommit", val);
+	
+	// Set the instance variable accordingly so it can be re-set after a transaction.
+	rb_iv_set(self, IV_AUTOCOMMIT, val);
 
+	// Always return nil if successful.
 	return Qnil;
 }
 
@@ -537,74 +752,163 @@ static VALUE cSedna_autocommit_set(VALUE self, VALUE auto_commit)
  */
 static VALUE cSedna_autocommit_get(VALUE self)
 {
-	return rb_iv_get(self, "@autocommit");
+	return rb_iv_get(self, IV_AUTOCOMMIT);
 }
 
 /*
  * call-seq:
  *   sedna.transaction { ... } -> nil
+ *   sedna.transaction -> nil
  *
- * Wraps the given block in a \transaction. If the block runs
- * completely, the \transaction is committed. If the stack is unwinded
- * prematurely, the \transaction is rolled back. This typically happens
- * when an \Exception is raised by calling +raise+ or a Symbol is thrown by
- * invoking +throw+. Note that Exceptions will not be rescued -- they will be
- * re-raised after rolling back the \transaction.
+ * Wraps the given block in a transaction. If the block runs completely, the
+ * transaction is committed. If the stack is unwinded prematurely, the
+ * transaction is rolled back. This typically happens when an exception is 
+ * raised by calling +raise+ or a Symbol is thrown by invoking +throw+. Note
+ * that exceptions will not be rescued -- they will be re-raised after rolling
+ * back the transaction.
  *
- * This method returns +nil+ if the \transaction is successfully committed
+ * This method returns +nil+ if the transaction is successfully committed
  * to the database. If the given block completes successfully, but the
- * \transaction fails to be committed, a Sedna::TransactionError will
- * be raised. 
+ * transaction fails to be committed, a Sedna::TransactionError will be raised.
+ *
+ * Transactions cannot be nested or executed simultaneously with the same
+ * connection. Calling this method inside a block that is passed to another
+ * transaction, or with the same connection in two concurrent threads will
+ * raise a Sedna::TransactionError on the second invocation.
  *
- * Transactions cannot be nested or executed simultaneously with the same connection.
- * Calling this method inside a block that is passed to another transaction, or
- * with the same connection in two concurrent threads will raise a
- * Sedna::TransactionError on the second invocation.
+ * If no block is given, this method only signals the beginning of a new
+ * transaction. A subsequent call to Sedna#commit or Sedna#rollback is required
+ * to end the transaction. Note that invoking this method with a block is the
+ * preferred way of executing transactions, because any exceptions that may be
+ * raised will automatically trigger a proper transaction rollback. Only call
+ * +commit+ and +rollback+ directly if you cannot use a block to wrap your
+ * transaction in.
  *
  * ==== Examples
  *
+ * Transactions are committed after the given block ends.
+ *
  *   sedna.transaction do
- *     count = sedna.execute "count(collection('my_col')/items)"  #=> 0
- *     sedna.execute "update insert <total>#{count}</total> into doc('my_doc')"
+ *     amount = 100
+ *     sedna.execute "update replace $balance in doc('my_account')/balance
+ *                    with <balance>{$balance - #{amount}}</balance>"
+ *     sedna.execute "update replace $balance in doc('your_account')/balance
+ *                    with <balance>{$balance + #{amount}}</balance>"
  *     # ...
  *   end
  *   # Transaction is committed.
  *
+ * Transactions are rolled back if something is thrown from inside the block.
+ *
+ *   sedna.transaction do
+ *     articles = sedna.execute "for $a in collection('articles')
+ *                               where $a/article/author = 'me' return $a"
+ *     throw :no_articles if articles.empty?
+ *     # ... never get here
+ *   end
+ *   # Transaction is rolled back.
+ *
+ * Transactions are also rolled back if an exception is raised inside the block.
+ *
  *   sedna.transaction do
- *     count = sedna.execute "count(collection('my_col')/items)"  #=> 0
- *     throw :no_items if count == 0
+ *     amount = 100
+ *     sedna.execute "update replace $balance in doc('my_account')/balance
+ *                    with <balance>{$balance - #{amount}}</balance>"
+ *     new_balance = sedna.execute "doc('my_account')/balance"
+ *     raise "Insufficient funds" if new_balance.to_i < 0
  *     # ... never get here
  *   end
  *   # Transaction is rolled back.
+ *
+ * If you really have to, you can also use transactions declaratively. Make
+ * sure to roll back the transaction if something goes wrong!
+ *
+ *   sedna.transaction
+ *   begin
+ *     amount = 100
+ *     sedna.execute "update replace $balance in doc('my_account')/balance
+ *                    with <balance>{$balance - #{amount}}</balance>"
+ *     sedna.execute "update replace $balance in doc('your_account')/balance
+ *                    with <balance>{$balance + #{amount}}</balance>"
+ *   rescue Exception
+ *     sedna.rollback
+ *   else
+ *     sedna.commit
+ *   end
  */
 static VALUE cSedna_transaction(VALUE self)
 {
 	int status;
 	SC *conn = sedna_struct(self);
 
-	SEDNA_AUTOCOMMIT_DISABLE(conn);
-	sedna_tr_begin(conn);
+	// Begin the transaction.
+	sedna_begin(conn);
 
-	rb_protect(rb_yield, Qnil, &status);
+	if(rb_block_given_p()) {
+		// Yield to the given block and protect it so we can always commit or rollback.
+		rb_protect(rb_yield, Qnil, &status);
 
-	if(status == 0) {
-		// Attempt to commit.
-		if(SEtransactionStatus(conn) == SEDNA_TRANSACTION_ACTIVE) sedna_tr_commit(conn);
-		else rb_raise(cSednaTrnError, "The transaction was prematurely ended, but no error was encountered. Did you rescue an exception inside the transaction?");
+		if(status == 0) {
+			// Attempt to commit if block completed successfully.
+			sedna_commit(conn, self);
+		} else {
+			// Stack has unwinded, attempt to roll back!
+			sedna_rollback(conn, self);
 
-		SWITCH_SEDNA_AUTOCOMMIT(conn, rb_iv_get(self, "@autocommit"));
-	} else {
-		// Stack has unwinded, attempt to roll back.
-		if(SEtransactionStatus(conn) == SEDNA_TRANSACTION_ACTIVE) sedna_tr_rollback(conn);
+			// Re-raise any exception or re-throw whatever was thrown.
+			rb_jump_tag(status);
+		}
+	}
 
-		SWITCH_SEDNA_AUTOCOMMIT(conn, rb_iv_get(self, "@autocommit"));
+	// Always return nil if successful.
+	return Qnil;
+}
 
-		rb_jump_tag(status); // Re-raise exception.
-	}
+/*
+ * call-seq:
+ *   sedna.commit -> nil
+ * 
+ * Commits a currently active transaction. Only use this method if you are
+ * specifying a transaction declaratively. Invoking Sedna#transaction with a
+ * block will automatically commit the transaction if the block finishes
+ * successfully.
+ *
+ * This method will raise a Sedna::TransactionError if no transaction is in
+ * progress when it is called.
+ */
+static VALUE cSedna_commit(VALUE self)
+{
+	SC *conn = sedna_struct(self);
 
+	// Attempt to commit.
+	sedna_commit(conn, self);
+
+	// Always return nil if successful.
 	return Qnil;
 }
 
+/*
+ * call-seq:
+ *   sedna.rollback -> nil
+ * 
+ * Rolls back a currently active transaction. Only use this method if you are
+ * specifying a transaction declaratively. Invoking Sedna#transaction with a
+ * block will automatically roll back the transaction if an exception is raised
+ * or if the stack is unwinded for whatever reason.
+ *
+ * This method will do nothing if no transaction is in progress when it is
+ * called.
+ */
+static VALUE cSedna_rollback(VALUE self)
+{
+	SC *conn = sedna_struct(self);
+
+	// Attempt to roll back.
+	sedna_rollback(conn, self);
+
+	// Always return nil if successful.
+	return Qnil;
+}
 
 // Initialize the extension ==============================================
 
@@ -621,7 +925,8 @@ void Init_sedna()
 	 *     :username => "SYSTEM",
 	 *     :password => "MANAGER",
 	 *   }
-	 *   Sedna.connect(connection_details) do |sedna|
+	 *
+	 *   Sedna.connect connection_details do |sedna|
 	 *     # Query the database.
 	 *     # The connection is closed automatically.
 	 *   end
@@ -636,19 +941,22 @@ void Init_sedna()
 	rb_define_singleton_method(cSedna, "blocking?", cSedna_s_blocking, 0);
 
 	rb_define_method(cSedna, "initialize", cSedna_initialize, 1);
-	rb_define_method(cSedna, "execute", cSedna_execute, 1);
-	rb_define_method(cSedna, "load_document", cSedna_load_document, -1);
+	rb_define_method(cSedna, "connected?", cSedna_connected, 0);
 	rb_define_method(cSedna, "close", cSedna_close, 0);
+	rb_define_method(cSedna, "reset", cSedna_reset, 0);
 	rb_define_method(cSedna, "transaction", cSedna_transaction, 0);
-
+	rb_define_method(cSedna, "commit", cSedna_commit, 0);
+	rb_define_method(cSedna, "rollback", cSedna_rollback, 0);
+	rb_define_method(cSedna, "execute", cSedna_execute, 1);
 	rb_define_undocumented_alias(cSedna, "query", "execute");
+	rb_define_method(cSedna, "load_document", cSedna_load_document, -1);
 
 	/*
 	 * Document-attr: autocommit
 	 *
 	 * When autocommit is set to +true+ (default), database queries can be run
 	 * without explicitly wrapping them in a transaction. Each query that is not
-	 * part of a \transaction is automatically committed to the database.
+	 * part of a transaction is automatically committed to the database.
 	 * Explicit transactions in auto-commit mode will still be committed
 	 * atomically.
 	 * 
@@ -664,9 +972,12 @@ void Init_sedna()
 	rb_define_method(cSedna, "autocommit", cSedna_autocommit_get, 0);
 
 	/*
-	 * The result set of a database query.
+	 * The result of a database query is stored in a Sedna::Set object, which
+	 * is a subclass of Array. Additional details about the executed query, such
+	 * as timing and debug information, may be added to Sedna::Set objects in
+	 * future versions of this library.
 	 */
-	// Unused so far...
+	// Stick to Array for result sets.
 	//cSednaSet = rb_define_class_under(cSedna, "Set", rb_cArray);
 
 	/*