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()

تعرض القيمة "صحيح" في حال الحصول على القفل. ستعرض هذه الطريقة خطأ إذا لم يتم استدعاء 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.');
}

المَعلمات

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

استرجاع الكرة

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


waitLock(timeoutInMillis)

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

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

المَعلمات

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

الرميات

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