locks_agent.md

Module locks_agent

• Description
• Data Types
• Function Index
• Function Details

Transaction agent for the locks system. Behaviours: gen_server.

Description

This module implements the recommended API for users of the locks system. While the locks_server has a low-level API, the locks_agent is the part that detects and resolves deadlocks.

The agent runs as a separate process from the client, and monitors the client, terminating immediately if it dies.

Data Types

option()

option() = {client, pid()} | {abort_on_deadlock, boolean()} | {await_nodes, boolean()} | {notify, boolean()}

transaction_status()

transaction_status() = no_locks | {have_all_locks, list()} | waiting | {cannot_serve, list()}

Function Index

await_all_locks/1	Waits for all active lock requests to be granted.
begin_transaction/1	Equivalent to begin_transaction(Objects, []).
begin_transaction/2	Starts an agent and requests a number of locks at the same time.
change_flag/3
end_transaction/1	Ends the transaction, terminating the agent.
lock/2
lock/3	Equivalent to lock(Agent, Obj, Mode, [node()], all, wait).
lock/4
lock/5
lock_info/1
lock_nowait/2
lock_nowait/3
lock_nowait/4
lock_nowait/5
lock_objects/2
record_fields/1
spawn_agent/1
start/0	Equivalent to start([]).
start/1	Starts an agent with options.
start_link/0	Equivalent to start_link([]).
start_link/1	Starts an agent with options, linking to the client.
surrender_nowait/4
transaction_status/1	Inquire about the current status of the transaction.

Function Details

await_all_locks/1

await_all_locks(Agent::agent()) -> lock_result()

Waits for all active lock requests to be granted.

This function will return once all active lock requests have been granted. If the agent determines that they cannot be granted, or if it has been instructed to abort, this function will raise an exception.

begin_transaction/1

begin_transaction(Objects::objs()) -> {agent(), lock_result()}

Equivalent to begin_transaction(Objects, []).

begin_transaction/2

begin_transaction(Objects::objs(), Opts::options()) -> {agent(), lock_result()}

Starts an agent and requests a number of locks at the same time.

For a description of valid options, see start/1.

This function will return once the given lock requests have been granted, or exit if they cannot be. If no initial lock requests are given, the function will not wait at all, but return directly.

change_flag/3

change_flag(Agent, Option, Bool) -> any()

end_transaction/1

end_transaction(Agent::agent()) -> ok

Ends the transaction, terminating the agent.

All lock requests issued via the agent will automatically be released.

lock/2

lock(Agent::pid(), Obj::oid()) -> {ok, list()}

lock/3

lock(Agent::pid(), Obj::oid(), Mode::mode()) -> {ok, list()}

Equivalent to lock(Agent, Obj, Mode, [node()], all, wait).

lock/4

lock(Agent::pid(), Obj::oid(), Mode::mode(), Where::[node()]) -> {ok, list()}

lock/5

lock(Agent::pid(), Obj::oid(), Mode::mode(), Where::[node()], R::req()) -> {ok, list()}

lock_info/1

lock_info(Agent) -> any()

lock_nowait/2

lock_nowait(A, O) -> any()

lock_nowait/3

lock_nowait(A, O, M) -> any()

lock_nowait/4

lock_nowait(A, O, M, W) -> any()

lock_nowait/5

lock_nowait(A, O, M, W, R) -> any()

lock_objects/2

lock_objects(Agent::pid(), Objects::objs()) -> ok

record_fields/1

record_fields(X1) -> any()

spawn_agent/1

spawn_agent(Options) -> any()

start/0

start() -> {ok, pid()}

Equivalent to start([]).

start/1

start(Options0::[option()]) -> {ok, pid()}

Starts an agent with options.

Options are:

• {client, pid()} - defaults to self(), indicating which process is the client. The agent will monitor the client, and only accept lock requests from it (this may be extended in future version).

• {link, boolean()} - default: false. Whether to link the current process to the agent. This is normally not required, but will have the effect that the current process (normally the client) receives an 'EXIT' signal if the agent aborts.

• {abort_on_deadlock, boolean()} - default: false. Normally, when deadlocks are detected, one agent will be picked to surrender a lock. This can be problematic if the client has already been notified that the lock has been granted. If {abort_on_deadlock, true}, the agent will abort if it would otherwise have had to surrender, and the client has been told that the lock has been granted.

• {await_nodes, boolean()} - default: false. If nodes 'disappear' (i.e. the locks_server there goes away) and {await_nodes, false}, the agent will consider those nodes lost and may abort if the lock request(s) cannot be granted without the lost nodes. If {await_nodes,true}, the agent will wait for the nodes to reappear, and reclaim the lock(s) when they do.

• {notify, boolean()} - default: false. If {notify, true}, the client will receive {locks_agent, Agent, Info} messages, where Info is either a #locks_info{} record or {have_all_locks, Deadlocks}.

start_link/0

start_link() -> {ok, pid()}

Equivalent to start_link([]).

start_link/1

start_link(Options::[option()]) -> {ok, pid()}

Starts an agent with options, linking to the client.

Note that even if {link, false} is specified in the Options, this will be overridden by {link, true}, implicit in the function name.

Linking is normally not required, as the agent will always monitor the client and terminate if the client dies.

See also start/1.

surrender_nowait/4

surrender_nowait(A, O, OtherAgent, Nodes) -> any()

transaction_status/1

transaction_status(Agent::agent()) -> transaction_status()

Inquire about the current status of the transaction. Return values:

no_locks

No locks have been requested

{have_all_locks, Deadlocks}

All requested locks have been claimed, Deadlocks indicates whether any deadlocks were resolved in the process.

waiting

Still waiting for some locks.

{cannot_serve, Objs}

Some lock requests cannot be served, e.g. because some nodes are unavailable.