entitytxn.core

Transaction state management

abort

(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

(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

(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

(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

(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?

(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?

(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

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?

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

lock!

(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

(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?

(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

(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

(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

(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

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