3 +--------------------------------------------------------------------+
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2020 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
10 | CiviCRM is free software; you can copy, modify, and distribute it |
11 | under the terms of the GNU Affero General Public License |
12 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
14 | CiviCRM is distributed in the hope that it will be useful, but |
15 | WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
17 | See the GNU Affero General Public License for more details. |
19 | You should have received a copy of the GNU Affero General Public |
20 | License and the CiviCRM Licensing Exception along |
21 | with this program; if not, contact CiviCRM LLC |
22 | at info[AT]civicrm[DOT]org. If you have questions about the |
23 | GNU Affero General Public License or the licensing of CiviCRM, |
24 | see the CiviCRM license FAQ at http://civicrm.org/licensing |
25 +--------------------------------------------------------------------+
31 * @copyright CiviCRM LLC (c) 2004-2020
35 class CRM_Core_Lock
implements \Civi\Core\Lock\LockInterface
{
38 * This variable (despite it's name) roughly translates to 'lock that we actually care about'.
40 * Prior to version 5.7.5 mysql only supports a single named lock. This variable is
41 * part of the skullduggery involved in 'say it's no so Frank'.
43 * See further comments on the aquire function.
47 public static $jobLog = FALSE;
50 * lets have a 3 second timeout for now
57 protected $_hasLock = FALSE;
64 * Use MySQL's GET_LOCK(). Locks are shared across all Civi instances
65 * on the same MySQL server.
68 * Symbolic name for the lock. Names generally look like
69 * "worker.mailing.EmailProcessor" ("{category}.{component}.{AdhocName}").
71 * Categories: worker|data|cache|...
72 * Component: core|mailing|member|contribute|...
73 * @return \Civi\Core\Lock\LockInterface
75 public static function createGlobalLock($name) {
76 return new static($name, NULL, TRUE);
80 * Use MySQL's GET_LOCK(), but apply prefixes to the lock names.
81 * Locks are unique to each instance of Civi.
84 * Symbolic name for the lock. Names generally look like
85 * "worker.mailing.EmailProcessor" ("{category}.{component}.{AdhocName}").
87 * Categories: worker|data|cache|...
88 * Component: core|mailing|member|contribute|...
89 * @return \Civi\Core\Lock\LockInterface
91 public static function createScopedLock($name) {
92 return new static($name);
96 * Use MySQL's GET_LOCK(), but conditionally apply prefixes to the lock names
97 * (if civimail_server_wide_lock is disabled).
100 * Symbolic name for the lock. Names generally look like
101 * "worker.mailing.EmailProcessor" ("{category}.{component}.{AdhocName}").
103 * Categories: worker|data|cache|...
104 * Component: core|mailing|member|contribute|...
105 * @return \Civi\Core\Lock\LockInterface
108 public static function createCivimailLock($name) {
109 $serverWideLock = \Civi
::settings()->get('civimail_server_wide_lock');
110 return new static($name, NULL, $serverWideLock);
114 * Initialize the constants used during lock acquire / release
116 * @param string $name
117 * Symbolic name for the lock. Names generally look like
118 * "worker.mailing.EmailProcessor" ("{category}.{component}.{AdhocName}").
120 * Categories: worker|data|cache|...
121 * Component: core|mailing|member|contribute|...
122 * @param int $timeout
123 * The number of seconds to wait to get the lock. 1 if not set.
124 * @param bool $serverWideLock
125 * Should this lock be applicable across your entire mysql server.
126 * this is useful if you have multiple sites running on the same
127 * mysql server and you want to limit the number of parallel cron
130 public function __construct($name, $timeout = NULL, $serverWideLock = FALSE) {
131 $config = CRM_Core_Config
::singleton();
132 $dsnArray = DB
::parseDSN($config->dsn
);
133 $database = $dsnArray['database'];
134 $domainID = CRM_Core_Config
::domainID();
135 if ($serverWideLock) {
136 $this->_name
= $name;
139 $this->_name
= $database . '.' . $domainID . '.' . $name;
141 // MySQL 5.7 doesn't like long lock names so creating a lock id
142 $this->_id
= sha1($this->_name
);
143 if (defined('CIVICRM_LOCK_DEBUG')) {
144 CRM_Core_Error
::debug_log_message('trying to construct lock for ' . $this->_name
. '(' . $this->_id
. ')');
146 $this->_timeout
= $timeout !== NULL ?
$timeout : self
::TIMEOUT
;
149 public function __destruct() {
156 * The advantage of mysql locks is that they can be used across processes. However, only one
157 * can be used at once within a process. An attempt to use a second one within a process
158 * prior to mysql 5.7.5 results in the first being released.
160 * The process here is
161 * 1) first attempt to grab a lock for a mailing job - self::jobLog will be populated with the
162 * lock id & a mysql lock will be created for the ID.
164 * If a second function in the same process attempts to grab the lock it will enter the hackyHandleBrokenCode routine
165 * which says 'I won't break a mailing lock for you but if you are not a civimail send process I'll let you
166 * pretend you have a lock already and you can go ahead with whatever you were doing under the delusion you
169 * @todo bypass hackyHandleBrokenCode for mysql version 5.7.5+
171 * If a second function in a separate process attempts to grab the lock already in use it should be rejected,
172 * but it appears it IS allowed to grab a different lock & unlike in the same process the first lock won't be released.
174 * All this means CiviMail locks are first class citizens & any other process gets a 'best effort lock'.
176 * @todo document naming convention for CiviMail locks as this is key to ensuring they work properly.
178 * @param int $timeout
181 * @throws \CRM_Core_Exception
183 public function acquire($timeout = NULL) {
184 if (!$this->_hasLock
) {
185 if (!CRM_Utils_SQL
::supportsMultipleLocks() && self
::$jobLog && CRM_Core_DAO
::singleValueQuery("SELECT IS_USED_LOCK( '" . self
::$jobLog . "')")) {
186 return $this->hackyHandleBrokenCode(self
::$jobLog);
189 $query = "SELECT GET_LOCK( %1, %2 )";
191 1 => [$this->_id
, 'String'],
192 2 => [$timeout ?
$timeout : $this->_timeout
, 'Integer'],
194 $res = CRM_Core_DAO
::singleValueQuery($query, $params);
196 if (defined('CIVICRM_LOCK_DEBUG')) {
197 CRM_Core_Error
::debug_log_message('acquire lock for ' . $this->_name
. '(' . $this->_id
. ')');
199 $this->_hasLock
= TRUE;
200 if (stristr($this->_name
, 'data.mailing.job.')) {
201 self
::$jobLog = $this->_id
;
205 if (defined('CIVICRM_LOCK_DEBUG')) {
206 CRM_Core_Error
::debug_log_message('failed to acquire lock for ' . $this->_name
. '(' . $this->_id
. ')');
210 return $this->_hasLock
;
214 * @return null|string
216 public function release() {
217 if ($this->_hasLock
) {
218 if (defined('CIVICRM_LOCK_DEBUG')) {
219 CRM_Core_Error
::debug_log_message('release lock for ' . $this->_name
. '(' . $this->_id
. ')');
221 $this->_hasLock
= FALSE;
223 if (self
::$jobLog == $this->_id
) {
224 self
::$jobLog = FALSE;
227 $query = "SELECT RELEASE_LOCK( %1 )";
228 $params = [1 => [$this->_id
, 'String']];
229 return CRM_Core_DAO
::singleValueQuery($query, $params);
234 * @return null|string
236 public function isFree() {
237 $query = "SELECT IS_FREE_LOCK( %1 )";
238 $params = [1 => [$this->_id
, 'String']];
239 return CRM_Core_DAO
::singleValueQuery($query, $params);
245 public function isAcquired() {
246 return $this->_hasLock
;
250 * CRM-12856 locks were originally set up for jobs, but the concept was extended to caching & groups without
251 * understanding that would undermine the job locks (because grabbing a lock implicitly releases existing ones)
252 * this is all a big hack to mitigate the impact of that - but should not be seen as a fix. Not sure correct fix
253 * but maybe locks should be used more selectively? Or else we need to handle is some cool way that Tim is yet to write :-)
254 * if we are running in the context of the cron log then we would rather die (or at least let our process die)
255 * than release that lock - so if the attempt is being made by setCache or something relatively trivial
256 * we'll just return TRUE, but if it's another job then we will crash as that seems 'safer'
258 * @param string $jobLog
259 * @throws CRM_Core_Exception
262 public function hackyHandleBrokenCode($jobLog) {
263 if (stristr($this->_name
, 'job')) {
264 CRM_Core_Error
::debug_log_message('lock acquisition for ' . $this->_name
. '(' . $this->_id
. ')' . ' attempted when ' . $jobLog . ' is not released');
265 throw new CRM_Core_Exception('lock acquisition for ' . $this->_name
. '(' . $this->_id
. ')' . ' attempted when ' . $jobLog . ' is not released');
267 if (defined('CIVICRM_LOCK_DEBUG')) {
268 CRM_Core_Error
::debug_log_message('(CRM-12856) faking lock for ' . $this->_name
. '(' . $this->_id
. ')');
270 $this->_hasLock
= TRUE;