Class Lock

قفل

تمثيل لقفل استبعاد متبادل.

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

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

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

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

  const scriptProperties = PropertiesService.getScriptProperties();

  const ticketNumber =
      Number(scriptProperties.getProperty('lastTicketNumber')) + 1;
  scriptProperties.setProperty('lastTicketNumber', ticketNumber);

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

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

الطُرق

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

مستندات تفصيلية

hasLock()

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

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

الإرجاع

‫Boolean: true إذا تم الحصول على القفل، أو false في الحالات الأخرى.

releaseLock()

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

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

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

tryLock(timeoutInMillis)

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

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

المَعلمات

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

الإرجاع

Boolean: true إذا تم الحصول على القفل، false في الحالات الأخرى

waitLock(timeoutInMillis)

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

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

المَعلمات

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

عمليات الطرح

Error: إذا انتهت مهلة الطريقة قبل الحصول على القفل