Documentation

CRM_Core_Lock
in package
implements LockInterface

Tags
copyright

CiviCRM LLC https://civicrm.org/licensing

Table of Contents

Interfaces

LockInterface
Lock interface.

Constants

TIMEOUT  = 3
lets have a 3 second timeout for now

Properties

$jobLog  : bool
This variable (despite it's name) roughly translates to 'lock that we actually care about'.
$_hasLock  : bool
$_id  : mixed
$_name  : mixed
$_timeout  : int
Lock Timeout

Methods

__construct()  : mixed
Initialize the constants used during lock acquire / release
__destruct()  : mixed
acquire()  : bool
Acquire lock.
createCivimailLock()  : LockInterface
Use MySQL's GET_LOCK(), but conditionally apply prefixes to the lock names (if civimail_server_wide_lock is disabled).
createGlobalLock()  : LockInterface
Use MySQL's GET_LOCK(). Locks are shared across all Civi instances on the same MySQL server.
createScopedLock()  : LockInterface
Use MySQL's GET_LOCK(), but apply prefixes to the lock names.
isAcquired()  : bool
isFree()  : null|string
release()  : null|string

Constants

TIMEOUT

lets have a 3 second timeout for now

public mixed TIMEOUT = 3

Properties

$jobLog

This variable (despite it's name) roughly translates to 'lock that we actually care about'.

public static bool $jobLog = \FALSE

Prior to version 5.7.5 mysql only supports a single named lock. This variable is part of the skullduggery involved in 'say it's no so Frank'.

See further comments on the acquire function.

$_hasLock

protected bool $_hasLock = \FALSE

$_id

protected mixed $_id

$_name

protected mixed $_name

$_timeout

Lock Timeout

protected int $_timeout

Methods

__construct()

Initialize the constants used during lock acquire / release

public __construct(string $name[, int $timeout = NULL ][, bool $serverWideLock = FALSE ]) : mixed
Parameters
$name : string

Symbolic name for the lock. Names generally look like "worker.mailing.EmailProcessor" ("{category}.{component}.{AdhocName}").

Categories: worker|data|cache|... Component: core|mailing|member|contribute|...

$timeout : int = NULL

The number of seconds to wait to get the lock. 1 if not set.

$serverWideLock : bool = FALSE

Should this lock be applicable across your entire mysql server. this is useful if you have multiple sites running on the same mysql server and you want to limit the number of parallel cron jobs - CRM-91XX

__destruct()

public __destruct() : mixed

acquire()

Acquire lock.

public acquire([int|null $timeout = NULL ]) : bool

The advantage of mysql locks is that they can be used across processes. However, only one can be used at once within a process. An attempt to use a second one within a process prior to mysql 5.7.5 results in the first being released.

The process here is

  1. first attempt to grab a lock for a mailing job - self::jobLog will be populated with the lock id & a mysql lock will be created for the ID.

If a second function in the same process attempts to grab the lock it will enter the hackyHandleBrokenCode routine which says 'I won't break a mailing lock for you but if you are not a civimail send process I'll let you pretend you have a lock already and you can go ahead with whatever you were doing under the delusion you have a lock.

Parameters
$timeout : int|null = NULL
Tags
todo

bypass hackyHandleBrokenCode for mysql version 5.7.5+

If a second function in a separate process attempts to grab the lock already in use it should be rejected, but it appears it IS allowed to grab a different lock & unlike in the same process the first lock won't be released.

All this means CiviMail locks are first class citizens & any other process gets a 'best effort lock'.

todo

document naming convention for CiviMail locks as this is key to ensuring they work properly.

throws
CRM_Core_Exception
Return values
bool

createCivimailLock()

Use MySQL's GET_LOCK(), but conditionally apply prefixes to the lock names (if civimail_server_wide_lock is disabled).

public static createCivimailLock(string $name) : LockInterface
Parameters
$name : string

Symbolic name for the lock. Names generally look like "worker.mailing.EmailProcessor" ("{category}.{component}.{AdhocName}").

Categories: worker|data|cache|... Component: core|mailing|member|contribute|...

Return values
LockInterface

createGlobalLock()

Use MySQL's GET_LOCK(). Locks are shared across all Civi instances on the same MySQL server.

public static createGlobalLock(string $name) : LockInterface
Parameters
$name : string

Symbolic name for the lock. Names generally look like "worker.mailing.EmailProcessor" ("{category}.{component}.{AdhocName}").

Categories: worker|data|cache|... Component: core|mailing|member|contribute|...

Return values
LockInterface

createScopedLock()

Use MySQL's GET_LOCK(), but apply prefixes to the lock names.

public static createScopedLock(string $name) : LockInterface

Locks are unique to each instance of Civi.

Parameters
$name : string

Symbolic name for the lock. Names generally look like "worker.mailing.EmailProcessor" ("{category}.{component}.{AdhocName}").

Categories: worker|data|cache|... Component: core|mailing|member|contribute|...

Return values
LockInterface

isAcquired()

public isAcquired() : bool
Return values
bool

isFree()

public isFree() : null|string
Return values
null|string

release()

public release() : null|string
Return values
null|string 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results