entitytxn.core — entity/entity-txn 0.1.4

Transaction state management

abort clj

(abort)

Abort the transaction. Transaction state is discarded and any :on-abort function is called. Further use of the transaction is not permitted.

abort is called if the transaction body incurs an exception.

assoc clj

(assoc map key val)

(assoc map key val & kvs)

As for clojure.core/assoc, however if the target map is managed track its mutation in the transaction. If the map is not managed the transaction state is unaffected.

The :assoc function in the transaction settings is used to perform the map operation. Consider using typeops/assoc to maintain value types and a fixed key set.

commit clj

(commit)

Commit the current transaction. Each instance joined for mutate will have TxnEvents.mutate-entity called, passing the original and current values. If any instances are entered into the transaction by the actions of the mutate calls, these will in turn be committed on subsequent passes. When all participants have been committed any :on-commit function will be called, passing all participants. This function cannot further affect transaction state.

create clj

(create instance)

Initialise the instance via TxnEvents.create-entity and join the result into the transaction for creation. If the instance is already managed or its identity is already joined in this or a parent transaction, this is an error. Returns the value being created in the transaction.

delete clj

(delete val)

Join the given value into the transaction for deletion. If the value is not managed or already scheduled for deletion this is an error. If the value has been previously created it is removed from the transaction. When successful calls TxnEvents.destroy-entity and returns true. Throws otherwise.

in-creation? clj

(in-creation? instance)

Return the instance if the given instance (or identity) is marked for creation in the current or any parent transaction. Falsy otherwise.

in-deletion? clj

(in-deletion? instance)

Return the instance, as truthy true if the given instance (or identity) is marked for deletion in the current or any parent transaction. Falsy otherwise.

in-transaction clj macro

(in-transaction args & body)

Opens a new transaction with optional arguments and runs the body in it, committing when the transaction closes. To specify args, pass a map which will be merged with any established by set-transaction-defaults, for example to supply a specific :on-commit function. Code runs in an implicit do, with any :on-start function called first.

If an exception occurs, abort is called and the exception rethrown, otherwise commit is called. Any :on-end function is always run. Returns nil.

joined? clj

(joined? instance)

Return true if the given instance (or identity) is joined in some way in the current or any parent transaction.

lock! clj

(lock! val)

(lock! val timeout)

Attempt to lock the given value obtaining the lock if it is available or waiting the specified timeout in milliseconds otherwise. A timeout of zero means unwilling to wait; negative means wait indefinitely.

Locks taken out become part of the current transaction's state. Locks held in the current transaction are released automatically when the transaction closes, and in reverse order of locking.

Returns the value as truthy if the lock was obtained, throws otherwise.

make-new-instance clj

(make-new-instance & args)

Makes a new, as yet unmanaged, instance of a domain type according to the given arguments, by calling TxnEvents.new-instance. The args are appropriate to the underlying system of domain types. Does not call TxnEvents.create-entity until create is called.

managed? clj

(managed? instance)

Return whether an instance is managed and therefore able to participate in a transaction for mutate/delete. An instance that is unmanaged can be marked for creation in the transaction.

merge clj

(merge & maps)

As for clojure.core/merge, however if the target map is managed track its state in the transaction. If the map is notmanaged the transaction state is unaffected.

The :merge function in the transaction settings is used to perform the map operation. Consider using typeops/assoc to maintain value types and a fixed key set.

read-instance clj

(read-instance key-val & args)

Read one or more instances via TxnEvents.read-entity. Within a transaction, for any values returned, the following occurs:

1. If the value is being deleted, do not return it (or if a non-unique key, remove it from the sequence)
2. If the value is being mutated, return the current value
3. Return the value as-is, marked as managed. Values in creation are not returned as there is no connection with the underlying persistence logic, however such values can be queried for participation with in-creation?.

Any args are passed to the underlying implementation, so must be compatible with that.

If no transaction is running the result(s) from the TxnEvents.read-entity is returned unmanaged. Instance(s) cannot take part in a transaction when acquired outside it.

set-transaction-defaults clj

(set-transaction-defaults & defaults)

Set up defaults to be used in transactions and nested transactions. This function will typically be called from an application's state management setup

• `:events connect transaction state to type and io system (defaults to none)
• :assoc how to assoc maps (defaults to clojure.core/assoc)
• :merge how to merge maps (defaults to clojure.core/merge)
• :on-commit function accepting two arguments [participants actions] to call when the transaction commits.
• :on-abort a function of zero arguments called when transaction aborts (exception or explicit)
• :on-start a function of zero arguments called before transaction body is executed
• :on-end function of zero arguments called after transaction commits or aborts

write-txn-state clj

(write-txn-state participants)

Write the values contained in the current transaction to backing store via TxnEvents.write-entity for create and mutate and TxnEvents.delete-entity for delete. This is a convenience function that clients can call via their :on-commit action, for example, within a transaction binding for the particular backing store.