water

Class Lockable<T extends Lockable<T>>

java.lang.Object

water.Iced<T>

water.Keyed<T>

water.Lockable<T>

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable, java.lang.Cloneable, Freezable<T>

Direct Known Subclasses:

Frame, Grid, Leaderboard, Model, PartialDependence

public abstract class Lockable<T extends Lockable<T>>
extends Keyed<T>

Lockable Keys - Keys locked during long running Jobs, to prevent overwriting in-use keys. E.g. model-building: expected to read-lock input Frames, and write-lock the output Model. Parser should write-lock the output Frame, to guard against double-parsing. This is a simple cooperative distributed locking scheme. Because we need distributed locking, the normal Java locks do not work. Because we cannot enforce good behavior, this is a cooperative scheme only. Supports:

• lock-and-delete-old-and-update (for new Keys)
• lock-and-delete (for removing old Keys)
• unlock

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
Key<Job>[]	_lockers List of Job Keys locking this Key.

Fields inherited from class water.Keyed

_key

Constructor Summary

Constructors

Constructor and Description
Lockable(Key<T> key) Create a Lockable object, if it has a Key.

Method Summary

Modifier and Type	Method and Description
T	delete_and_lock() Write-lock this._key by job_key, and delete any prior mapping.
T	delete_and_lock(Job job)
T	delete_and_lock(Key<Job> job_key)
T	delete_and_lock(Key<Job> job_key, boolean cascade)
void	delete() Write-lock 'this' and delete; blocking.
void	delete(boolean cascade)
static void	delete(Key key) Write-lock key and delete; blocking.
Futures	delete(Key<Job> job_key, Futures fs, boolean cascade) Write-lock 'this' and delete.
void	read_lock(Key<Job> job_key) Atomically get a read-lock on this, preventing future deletes or updates
static void	read_lock(Key k, Job job) Atomically get a read-lock on Key k, preventing future deletes or updates
static void	read_lock(Key k, Key<Job> job_key)
void	unlock_all() Force-unlock (break a lock) all lockers; useful in some debug situations.
T	unlock() Atomically set a new version of self and unlock.
T	unlock(Job job)
T	unlock(Key<Job> job_key)
T	unlock(Key<Job> job_key, boolean exact)
T	update() Atomically set a new version of self, without changing the locking.
T	update(Job job)
T	update(Key<Job> job_key)
void	write_lock_to_read_lock(Key<Job> job_key) Atomically convert an existing write-lock on this to a read-lock, preventing future deletes or updates
Lockable	write_lock() Write-lock this._key by job_key.
Lockable	write_lock(Job job)
Lockable	write_lock(Key<Job> job_key)

Methods inherited from class water.Keyed

checksum_impl, checksum_impl, checksum, checksum, getKey, makeSchema, readAll_impl, readAll, remove_impl, remove_impl, remove_self_key_impl, remove, remove, remove, remove, remove, remove, removeQuietly, writeAll_impl, writeAll

Methods inherited from class water.Iced

asBytes, clone, copyOver, frozenType, read, readExternal, readJSON, reloadFromBytes, toJsonBytes, toJsonString, write, writeExternal, writeJSON

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_lockers

public transient Key<Job>[] _lockers

List of Job Keys locking this Key.

• Write-locker job is in _lockers[0 ]. Can be null locker.
• Read -locker jobs are in _lockers[1+].
• Unlocked has _lockers equal to null.
• Only 1 situation will be true at a time; atomically updated.
• Transient, because this data is only valid on the master node.

Constructor Detail

Lockable

public Lockable(Key<T> key)

Create a Lockable object, if it has a Key.

Method Detail

write_lock

public Lockable write_lock()

Write-lock this._key by job_key. Throws IAE if the Key is already locked.

Returns:

the old POJO mapped to this Key, generally for deletion.

write_lock

public Lockable write_lock(Job job)

write_lock

public Lockable write_lock(Key<Job> job_key)

delete_and_lock

public T delete_and_lock()

Write-lock this._key by job_key, and delete any prior mapping. Throws IAE if the Key is already locked.

Returns:

self, locked by job_key

delete_and_lock

public T delete_and_lock(Job job)

delete_and_lock

public T delete_and_lock(Key<Job> job_key)

delete_and_lock

public T delete_and_lock(Key<Job> job_key,
                         boolean cascade)

delete

public static void delete(Key key)

Write-lock key and delete; blocking. Throws IAE if the key is already locked.

delete

public final void delete()

Write-lock 'this' and delete; blocking. Throws IAE if the _key is already locked. Subclasses that need custom deletion logic should override Keyed.remove_impl(Futures, boolean) as by contract, the only difference between delete() and Keyed.remove() is that `delete` first write-locks `this`.

delete

public final void delete(boolean cascade)

delete

public final Futures delete(Key<Job> job_key,
                            Futures fs,
                            boolean cascade)

Write-lock 'this' and delete. Throws IAE if the _key is already locked. Subclasses that need custom deletion logic should override Keyed.remove_impl(Futures, boolean).

read_lock

public static void read_lock(Key k,
                             Job job)

Atomically get a read-lock on Key k, preventing future deletes or updates

read_lock

public static void read_lock(Key k,
                             Key<Job> job_key)

read_lock

public void read_lock(Key<Job> job_key)

Atomically get a read-lock on this, preventing future deletes or updates

write_lock_to_read_lock

public void write_lock_to_read_lock(Key<Job> job_key)

Atomically convert an existing write-lock on this to a read-lock, preventing future deletes or updates

update

public T update()

Atomically set a new version of self, without changing the locking. Typically used to upgrade a write-locked Model to a newer version with more training iterations.

update

public T update(Job job)

update

public T update(Key<Job> job_key)

unlock

public T unlock()

Atomically set a new version of self and unlock.

unlock

public T unlock(Job job)

unlock

public T unlock(Key<Job> job_key)

unlock

public T unlock(Key<Job> job_key,
                boolean exact)

unlock_all

public void unlock_all()

Force-unlock (break a lock) all lockers; useful in some debug situations.