#import <NetcdfStepPathLock.h>
Public Member Functions | |
| (id) | - initWithPath: |
| Inits the new lock if the path does not already have a lock, else returns the shared one. | |
| (unsigned int) | - shareCount |
| Returns the number of objects sharing this lock. | |
| (NSString *) | - path |
| Returns the path associated with this lock. | |
Static Public Member Functions | |
| (NetcdfStepPathLock *) | + lockForPath: |
| Returns the shared lock for a path, or nil if the path has no lock. | |
| (NetcdfStepPathLock *) | + lockWithPath: |
| Makes a new lock if the path does not already have a lock, else returns the shared one. | |
| (unsigned int) | + shareCountForPath: |
| Returns the count of shared objects for the lock associated with a path. | |
| (void) | + releaseLockForPath: |
| Decrements the count of shared objects for the lock associated with a path. | |
| (NSMutableDictionary *) | + pathLocks |
| Returns a dictionary of all the locks and associated paths currently in use. | |
Since one netCDF data file may have more than one NetcdfDataset objects that refer to it, locking needs to be handled at a higher level than the object. This class associates one lock with each open data file, and provides it to any NetcdfDataset object that uses that file. Therefore NetcdfDatasets in different threads that might compete for the same file can use the same lock to regulate access. Together NetcdfDataset and NetcdfStepPathLock manage the instantiation and disposal of the locks. Whenever a dataset is opened or created with share == YES, a lock is created or shared. The lock is used during initialization of the dataset.
NetcdfStepPathLock is a subclass of NSLock and inherits all its fields and methods. The routine data access methods in NetcdfAttribute and NetcdfVariable do not use the lock. How this lock is used is at the discretion of the application programmer.
A counting system keeps track of how many datasets are sharing one pathLock. Because the pathLocks are retained in a static dictionary managed by the class, it is necessary to use the class method +releaseLockForPath: to remove a pathLock from the class dictionary when it is no longer needed. NetcdfDataset implements this for you in its dealloc method.
As a matter of practice, netCDF 3 is not designed to be thread-safe. Read-only access should be thread-safe. For read/write access, it is necessary to use ncSync after each write and before each read of the dataset; this is especially important when accessing an unlimited variable. Be very careful using define mode with multi-threaded access; exit define mode before unlocking. Therefore, any operation that alters the structure of the dataset should be completed and synchronized inside a single lock. Finally, access by more than one application or process is not protected; NetcdfStepPathLock provides safe access only for multiple threads within a single application or process.
| - (id) initWithPath: | (NSString *) | newPath |
Inits the new lock if the path does not already have a lock, else returns the shared one.
The path need not be a valid file. Returns the lock.
| + (NetcdfStepPathLock *) lockWithPath: | (NSString *) | newPath |
Makes a new lock if the path does not already have a lock, else returns the shared one.
The path need not be a valid file. Returns an autoreleased lock.
| + (NSMutableDictionary *) pathLocks |
Returns a dictionary of all the locks and associated paths currently in use.
This is useful mostly for debugging or disaster recovery. It should not be used under normal circumstances.
| + (void) releaseLockForPath: | (NSString *) | aPath |
Decrements the count of shared objects for the lock associated with a path.
Releases the lock when count reaches zero.
1.5.7.1