Class Lock

قفل

تمثّل هذه السمة قفل الاستبعاد المتبادل.

تتيح هذه الفئة للنصوص البرمجية التأكد من أن مثيل واحد فقط من النص البرمجي ينفذ عملية كل قسم من التعليمات البرمجية في كل مرة. يُعد هذا مفيدًا بشكل خاص لعمليات الاستدعاء والمشغلات، حيث يكون لدى المستخدم إجراء تغييرات على مورد مشترك وتريد التأكد من عدم والتصادمات.

يوضّح المثال التالي كيفية استخدام القفل في معالِج إرسال النموذج. 

// Generates a unique ticket number for every form submission.
function onFormSubmit(e) {
  var targetCell = e.range.offset(0, e.range.getNumColumns(), 1, 1);

  // Gets a script lock before modifying a shared resource.
  var lock = LockService.getScriptLock();
  // Waits for up to 30 seconds for other processes to finish.
  lock.waitLock(30000);

  var ticketNumber = Number(ScriptProperties.getProperty('lastTicketNumber'))   1;
  ScriptProperties.setProperty('lastTicketNumber', ticketNumber);

  // Releases the lock so that other processes can continue.
  lock.releaseLock();

  targetCell.setValue(ticketNumber);
}
 وبدون خدمة "القفل"، إذا أرسل مستخدمان النموذج في الوقت نفسه تقريبًا، قد ينتهي الأمر بالتشابه بين الأرقام، نظرًا لأن السمة lastTicketNumber قد تتغير بعد ذلك تمت قراءة من ScriptProperties ولكن قبل كتابة القيمة الجديدة مرة أخرى.

الطُرق

الطريقةنوع الإرجاعوصف قصير
hasLock()Booleanتعرض القيمة "صحيح" في حال الحصول على القفل.
releaseLock()voidيؤدي هذا الإجراء إلى فتح القفل، ما يسمح بمتابعة العمليات الأخرى التي تنتظر القفل.
tryLock(timeoutInMillis)Booleanمحاولات استعادة القفل، تنتهي المهلة بعد العدد المحدّد من المللي ثانية.
waitLock(timeoutInMillis)voidمحاولات الاستحواذ على القفل، انتهت المهلة مع استثناء بعد العدد المقدم مللي ثانية.

الوثائق التفصيلية

hasLock()

تعرض القيمة "صحيح" في حال الحصول على القفل. ستعرض هذه الطريقة القيمة "false" إذا كانت السمة tryLock(timeoutInMillis) أو لم يتم مطلقًا الاتصال بـ "waitLock(timeoutInMillis)" أو انتهت المهلة قبل استعادة القفل أو إذا تم طلب "releaseLock()". 

var lock = LockService.getScriptLock();
lock.tryLock(10000);
if (!lock.hasLock()) {
  Logger.log('Could not obtain lock after 10 seconds.');
}

الإرجاع

Boolean — صحيح إذا تم الاستيلاء على القفل، وخطأ في الحالات الأخرى

releaseLock()

يؤدي هذا الإجراء إلى فتح القفل، ما يسمح بمتابعة العمليات الأخرى التي تنتظر القفل. القفل هو يتم تحريره تلقائيًا عند إنهاء النص البرمجي، ولكن لتحقيق فعالية، من الأفضل إصداره عندما لا تحتاج إلى إمكانية الوصول الحصري إلى أحد أقسام الرمز البرمجي. ليس لهذه الطريقة أي تأثير في حال عدم الاستحواذ على القفل.

لاحظ أنه إذا كنت تعمل باستخدام جدول بيانات، فيجب عليك استدعاء SpreadsheetApp.flush() قبل تحرير القفل، لتنفيذ جميع التغييرات المعلَّقة على جدول البيانات مع الوصول الحصري إليه. 

var lock = LockService.getScriptLock();
lock.waitLock(10000);
// Do some work on a shared resource.
lock.releaseLock();

tryLock(timeoutInMillis)

محاولات استعادة القفل، تنتهي المهلة بعد العدد المحدّد من المللي ثانية. هذه الطريقة لن يكون له أي تأثير إذا كان القفل قد تم الاستيلاء عليه من قبل. 

var lock = LockService.getScriptLock();
var success = lock.tryLock(10000);
if (!success) {
  Logger.log('Could not obtain lock after 10 seconds.');
}

المعلمات

الاسمالنوعالوصف
timeoutInMillisIntegerمدة الانتظار للحصول على القفل بالمللي ثانية

الإرجاع

Boolean — صحيح إذا تم الاستيلاء على القفل، وخطأ في الحالات الأخرى

waitLock(timeoutInMillis)

محاولات الاستحواذ على القفل، انتهت المهلة مع استثناء بعد العدد المقدم مللي ثانية. هذه الطريقة مماثلة لطريقة tryLock(timeoutInMillis) باستثناء أنّها تنشئ استثناءً. عندما يتعذر إلغاء القفل بدلاً من عرض القيمة false. 

var lock = LockService.getScriptLock();
try {
  lock.waitLock(10000);
} catch (e) {
  Logger.log('Could not obtain lock after 10 seconds.');
}

المعلمات

الاسمالنوعالوصف
timeoutInMillisIntegerمدة الانتظار للحصول على القفل بالمللي ثانية

الرميات

Error: إذا انتهت مهلة الطريقة قبل تثبيت القفل