About Usage Methods

The in-use list provides the object with information such as:

• The number of container windows into which the object has been inserted (USAGE_RECORD)

• The number of open views (contents and settings) of the object that already exist (USAGE_OPENVIEW)

• How much memory the object has allocated (USAGE_MEMORY)

• How many awakened shadows there are of the object (USAGE_LINK)

• Which application opened the object (USAGE_OPENFILE). Note that this information only applies to data file objects.

All objects that the user interacts with are actually just records that have been inserted into a container control. A container is an object, such as a folder, which also has an in-use list. Because of the close relationship between an object's in-use list and container objects, this chapter includes a description of methods that are relevant to container usage as well as object usage. Object Usage methods, as shown in the following table, allow an object to keep track of its resources and how it is being used:

┌─────────────────────────┬───────────────────────────────────┐│Method Name              │Description                        │
├─────────────────────────┼───────────────────────────────────┤
│wpAddToObjUseList        │Adds an object to the list of      │
│                         │objects in use by the object.      │
├─────────────────────────┼───────────────────────────────────┤
│wpAssertObjectMutexSem   │This instance method verifies that │
│                         │an object's mutex semaphore is held│
│                         │for the current thread.            │
├─────────────────────────┼───────────────────────────────────┤
│wpCnrDeleteUseItem       │Deletes the object's USAGE_RECORD  │
│                         │use-item for the specified         │
│                         │container.                         │
├─────────────────────────┼───────────────────────────────────┤
│wpDeleteFromObjUseList   │Deletes an object from the list of │
│                         │objects in use by the object.      │
├─────────────────────────┼───────────────────────────────────┤
│wpFindUseItem            │Retrieves an object from the list  │
│                         │of objects in use by the object.   │
├─────────────────────────┼───────────────────────────────────┤
│wpFindViewItem           │Retrieves a USAGE_OPENVIEW item    │
│                         │from the list of items in use by   │
│                         │the object.                        │
├─────────────────────────┼───────────────────────────────────┤
│wpIsLocked               │Tells you whether the object is    │
│                         │locked or not.                     │
├─────────────────────────┼───────────────────────────────────┤
│wpLockObject             │Increases the lock counter for the │
│                         │object. Objects that are locked    │
│                         │will not be made dormant.          │
├─────────────────────────┼───────────────────────────────────┤
│wpReleaseObjectMutexSem  │Releases the mutex semaphore for an│
│                         │object. Each object has associated │
│                         │with it a mutex semaphore that can │
│                         │be used to serialize access to     │
│                         │resources.                         │
├─────────────────────────┼───────────────────────────────────┤
│wpRequestObjectMutexSem  │Requests the mutex semaphore for an│
│                         │object. Each object has associated │
│                         │with it a mutex semaphore that can │
│                         │be used to serialize access to     │
│                         │resources.                         │
├─────────────────────────┼───────────────────────────────────┤
│wpUnlockObject           │Unlocks the object so that it can  │
│                         │be made dormant.                   │
└─────────────────────────┴───────────────────────────────────┘

The in-use list is a linked list of USEITEM data structures. It consists of an item type and a pointer to the next USEITEM data structure, immediately followed by an item type-specific data structure. The types of items that can be added to an object's in-use list and the type-specific data structures that follow each USEITEM data structure are shown in the following table:

┌───────────────┬──────────┬───────────────────────────────────┐
│Item           │Structure │Description                        │
├───────────────┼──────────┼───────────────────────────────────┤
│USAGE_LINK     │LINKITEM  │A shadow of the object has been    │
│               │          │awakened.                          │
├───────────────┼──────────┼───────────────────────────────────┤
│USAGE_MEMORY   │MEMORYITEM│Memory has been allocated by       │
│               │          │wpAllocMem.                        │
├───────────────┼──────────┼───────────────────────────────────┤
│USAGE_OPENFILE │VIEWFILE  │The object (if a data file) has    │
│               │          │been opened.                       │
├───────────────┼──────────┼───────────────────────────────────┤
│USAGE_OPENVIEW │VIEWITEM  │A view of the object has been      │
│               │          │opened.                            │
├───────────────┼──────────┼───────────────────────────────────┤
│USAGE_RECORD   │RECORDITEM│The object has been inserted into a│
│               │          │container window.                  │
└───────────────┴──────────┴───────────────────────────────────┘