GetLock Method (IWorkbookSet)

Interrupts background calculation if necessary and acquires an exclusive lock on the workbook set.

Syntax

Visual Basic
C#

'Declaration
 
Sub GetLock()

'Usage
 
Dim instance As IWorkbookSet
 
instance.GetLock()

void GetLock()

Remarks

This method is thread safe.

A lock must be acquired on a workbook set before using the workbook set from multiple threads. This includes any access to any properties or methods of any object belonging to the workbook set, unless the property or method is explicitly marked as thread safe. Since all Windows Forms components from SpreadsheetGear use GetLock and ReleaseLock whenever they access a workbook set, and since BackgroundCalculation is on by default, GetLock and ReleaseLock must be used to access a workbook set which is attached to any of these Windows Forms components.

To eliminate the need to use GetLock and ReleaseLock when using Windows Forms components from SpreadsheetGear, set BackgroundCalculation to false or set Calculation to Calculation.Manual, and limit access to the workbook set to the thread which created the Windows Forms component(s). The WorkbookView control allows the BackgroundCalculation property to be set in the WorkbookView Smart Tag and in the WorkbookView property list, although doing so will typically hurt performance significantly.

There is no need to use GetLock and ReleaseLock when using a workbook set which is not attached to any Windows Forms components from SpreadsheetGear. However, these methods may still be useful to synchronize access to a workbook set, particularly in applications which would benefit from interruptible background calculation.

All components in the SpreadsheetGear.Windows.Forms namespace adhere to the standard Windows Forms threading model. Members of any object in the SpreadsheetGear.Windows.Forms namespace must not be accessed from any thread other than the thread which created the object. Calling System.Windows.Forms.Control.BeginInvoke is valid when holding a lock on a workbook set. However, calling System.Windows.Forms.Control.Invoke while holding a lock on a workbook set is likely to result in a deadlock.

Calls to GetLock may be nested. ReleaseLock must be called once for each call to GetLock. The recommended best practice is to call GetLock followed by a try block where work is done, and then call ReleaseLock in a finally block.

Example

Demonstrate using a workbook set in a thread safe manner.

void DoSomeThreadSafeWork(IWorkbookSet workbookSet)
        {
            // Interrupt background calculation if necessary and acquire an
            // exclusive lock on the workbook set.
            workbookSet.GetLock();
 
            try {
                // Do some work...
            }
            finally {
                // Release the lock on the workbook set and start background
                // calculation if appropriate.
                workbookSet.ReleaseLock();
            }
        }

Visual Basic

Sub DoSomeThreadSafeWork(ByVal workbookSet As IWorkbookSet)
            ' Interrupt background calculation if necessary and acquire an 
            ' exclusive lock on the workbook set. 
            workbookSet.GetLock()
 
            Try
                ' Do some work... 
            Finally
                ' Release the lock on the workbook set and start background 
                ' calculation if appropriate. 
                workbookSet.ReleaseLock()
            End Try
        End Sub 'DoSomeThreadSafeWork

Requirements

Target Platforms: Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

Reference

IWorkbookSet Interface
IWorkbookSet Members
HasLock Property
ReleaseLock Method
RewindLock Method
UnwindLock Method
BeginUpdate Method
EndUpdate Method
BackgroundCalculation Property