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 اما قبل از نوشتن مقدار جدید، تغییر کند.

روش‌ها

روش	نوع بازگشتی	شرح مختصر
has Lock()	Boolean	اگر قفل ایجاد شده باشد، true را برمی‌گرداند.
release Lock()	void	قفل را آزاد می‌کند و به سایر فرآیندهای منتظر قفل اجازه می‌دهد تا ادامه دهند.
try Lock(timeoutInMillis)	Boolean	تلاش برای دریافت قفل، پس از تعداد میلی‌ثانیه‌های ارائه شده، پایان می‌یابد.
wait Lock(timeoutInMillis)	void	تلاش برای به دست آوردن قفل، با یک استثنا پس از تعداد میلی‌ثانیه ارائه شده، پایان می‌یابد.

مستندات دقیق

hasLock()

اگر قفل ایجاد شده باشد، true را برمی‌گرداند. اگر tryLock(timeoutInMillis) یا waitLock(timeoutInMillis) هرگز فراخوانی نشده باشند، قبل از بازیابی قفل، مهلت آن تمام شده باشد، یا اگر releaseLock() فراخوانی شده باشد، false را برمی‌گرداند.

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.');
}

پارامترها

نام	نوع	توضیحات
timeout In Millis	Integer	مدت زمان انتظار برای دریافت قفل، بر حسب میلی‌ثانیه.

بازگشت

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.');
}

پارامترها

نام	نوع	توضیحات
timeout In Millis	Integer	مدت زمان انتظار برای دریافت قفل، بر حسب میلی‌ثانیه.

پرتاب‌ها

Error - اگر مهلت زمانی متد قبل از دریافت قفل تمام شده باشد