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


168
169
170
171
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 168

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


141
142
143
144
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 141

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.



182
183
184
185
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 182

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

#error? ⇒ false, true

Note:

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

Returns whether the transaction incurred an error.

Returns:

  • (false, true) —

    whether the transaction incurred an error.



214
215
216
217
218
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 214

static VALUE transaction_is_error(VALUE self) {
  TRANSACTION(self, &lmdb_transaction_type, transaction);
  // MDB_TXN_ERROR
  return (transaction->flags & 0x02) ? Qtrue : Qfalse;
}

#finished? ⇒ false, true

Note:

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

Returns whether the transaction is finished.

Returns:

  • (false, true) —

    whether the transaction is finished.



203
204
205
206
207
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 203

static VALUE transaction_is_finished(VALUE self) {
  TRANSACTION(self, &lmdb_transaction_type, transaction);
  // MDB_TXN_FINISHED
  return (transaction->flags & 0x01) ? Qtrue : Qfalse;
}

#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.



192
193
194
195
196
 
# File 'ext/lmdb_ext/lmdb_ext.c', line 192

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