Class: LMDB::Transaction

Inherits:
Object
  • Object
show all
Defined in:
ext/lmdb_ext/lmdb_ext.c,
ext/lmdb_ext/lmdb_ext.c

Overview

The LMDB environment supports transactional reads and updates. By default, these provide the standard ACID (atomicity, consistency, isolation, durability) behaviors.

Transactions can be committed or aborted. When a transaction is committed, all its effects take effect in the database atomically. When a transaction is aborted, none of its effects take effect.

Transactions span the entire environment. All the updates made in the course of an update transaction – writing records across all databases, creating databases, and destroying databases – are either completed atomically or rolled back.

Transactions can be nested. A child transaction can be started within a parent transaction. The child transaction can commit or abort, at which point the effects of the child become visible to the parent transaction or not. If the parent aborts, all of the changes performed in the context of the parent – including the changes from a committed child transaction – are rolled back.

To create a transaction, call Environment#transaction and supply a block for the code to execute in that transaction.

Examples:

Typical usage

env = LMDB.new "databasedir"
db1 = env.database "database1"
env.transaction do |parent|
  db2 = env.database "database2", :create => true
                        #=> creates a new database, but it isn't
                        #=> yet committed to storage
  db1['x']              #=> nil
  env.transaction do |child1|
    db2['a'] = 'b'
    db1['x'] = 'y'
  end
                        #=> first child transaction commits
                        #=> changes are visible within the parent transaction
                        #=> but are not yet permanent
  db1['x']              #=> 'y'
  db2['a']              #=> 'a'
  env.transaction do |child2|
    db2['a'] = 'def'
    db1['x'] = 'ghi'
    child2.abort
                        #=> second child transaction aborts and rolls
                        #=> back its changes
  end
  db1['x']              #=> 'y'
  db2['a']              #=> 'a'
end
                        #=> parent transaction commits and writes database2
                        #=> and the updates from transaction child1 to
                        #=> storage.

Instance Method Summary collapse

Instance Method Details

#abort ⇒ Object

Note:

After aborting a transaction, no further database operations should be done in the block. Any cursors created in the context of the transaction will no longer be valid.

Abort a transaction in process. Any subtransactions of this transaction will be aborted as well.

Examples:

Single transaction

env.transaction do |txn|
  # ... modify the databases ...
  txn.abort
  # modifications are rolled back
end

Child transactions

env.transaction do |txn1|
  env.transaction.do |txn2|
     txn1.abort      # txn1 and txn2 are both aborted
  end
end


110
111
112
113
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 110

static VALUE transaction_abort(VALUE self) {
        transaction_finish(self, 0);
        return Qnil;
}

#commit ⇒ Object

Note:

After committing a transaction, no further database operations should be done in the block. Any cursors created in the context of the transaction will no longer be valid.

Commit a transaction in process. Any subtransactions of this transaction will be committed as well.

One does not normally need to call commit explicitly; a commit is performed automatically when the block supplied to Environment#transaction exits normally.

Examples:

Single transaction

env.transaction do |txn|
  # ... modify the databases ...
  txn.commit
end

Child transactions

env.transaction do |txn1|
  env.transaction.do |txn2|
     txn1.commit      # txn1 and txn2 are both committed
  end
end


83
84
85
86
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 83

static VALUE transaction_commit(VALUE self) {
        transaction_finish(self, 1);
        return Qnil;
}

#env ⇒ Environment

Returns the environment in which this transaction is running.

Examples:

env.transaction do |t|
  env == t.env
  # should be true
end

Returns:

  • (Environment) —

    the environment in which this transaction is running.



124
125
126
127
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 124

static VALUE transaction_env(VALUE self) {
        TRANSACTION(self, transaction);
        return transaction->env;
}

#readonly? ⇒ false, true

Note:

This predicate is considered unstable; do not get used to it.

Returns whether the transaction is read-only.

Returns:

  • (false, true) —

    whether the transaction is read-only.



134
135
136
137
138
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 134

static VALUE transaction_is_readonly(VALUE self) {
    TRANSACTION(self, transaction);
    //MDB_txn* txn = transaction->txn;
    return (transaction->flags & MDB_RDONLY) ? Qtrue : Qfalse;
}