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 إذا تم الحصول على القفل. ستُرجع هذه الطريقة قيمة خاطئة إذا لم يتم استدعاء 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: صحيح إذا تم الحصول على القفل، وخطأ بخلاف ذلك


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: صحيح إذا تم الحصول على القفل، وخطأ بخلاف ذلك


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 - إذا انتهت مهلة الطريقة قبل الحصول على القفل