sqlalchemy_dlock.lock.mysql module

class sqlalchemy_dlock.lock.mysql.MysqlSadLockMixin(*, key: TKey, convert: Callable[[TKey], str] | None = None, **kwargs)

Bases: object

A Mix-in class for MySQL named lock

Parameters:

• key (TKey) –

  MySQL named lock requires the key given by string.

  If key is not a str:

  • When bytes or alike, the constructor tries to decode it with default encoding:

    key = key.decode()
    

  • Otherwise the constructor force convert it to str:

    key = str(key)
    

  • Or you can specify a convert function to that argument

• convert (Callable[[TKey], str] | None) –

  Custom function to covert key to required data type.

  Example

  def convert(value) -> str:
      # get a string key by `value`
      return the_string_covert_from_value
  

class sqlalchemy_dlock.lock.mysql.MysqlSadLock(connection_or_session: Connection | Session | scoped_session, key, **kwargs)

Bases: MysqlSadLockMixin, BaseSadLock[str]

A distributed lock implemented by MySQL named-lock

See also

https://dev.mysql.com/doc/refman/8.0/en/locking-functions.html

Caution

To MySQL locking function, it is even possible for a given session to acquire multiple locks for the same name. Other sessions cannot acquire a lock with that name until the acquiring session releases all its locks for the name. When perform multiple acquire() for a key on the same SQLAlchemy connection, latter acquire() will success immediately no wait and never block, it causes cascade lock instead!

Parameters:

• connection_or_session (Connection | Session | scoped_session) – BaseSadLock.connection_or_session

• key – BaseSadLock.key

• **kwargs – other named parameters pass to BaseSadLock and MysqlSadLockMixin

acquire(block: bool = True, timeout: float | int | None = None, *args, **kwargs) → bool

Acquire a lock, blocking or non-blocking.

• With the block argument set to True (the default), the method call will block until the lock is in an unlocked state, then set it to locked and return True.

• With the block argument set to False, the method call does not block. If the lock is currently in a locked state, return False; otherwise set the lock to a locked state and return True.

• When invoked with a positive, floating-point value for timeout, block for at most the number of seconds specified by timeout as long as the lock can not be acquired. Invocations with a negative value for timeout are equivalent to a timeout of zero. Invocations with a timeout value of None (the default) set the timeout period to infinite. The timeout parameter has no practical implications if the block argument is set to False and is thus ignored. Returns True if the lock has been acquired or False if the timeout period has elapsed.

Parameters:

• block (bool)

• timeout (float | int | None)

Return type:

bool

release()

Release a lock.

Since the class is thread-local, this cannot be called from other thread or process, and also can not be called from other connection. (Although PostgreSQL’s shared advisory lock supports so).

When the lock is locked, reset it to unlocked, and return. If any other threads are blocked waiting for the lock to become unlocked, allow exactly one of them to proceed.

When invoked on an unlocked lock, a ValueError is raised.

There is no return value.