| The Casbah Project: APIs and Reference Manual: Developer's Release 1 | ||
|---|---|---|
| Prev | The Casbah Project: NatrounAPI | Next |
A Conformant Natroun Driver may implement all, none, or some of the following methods depending on that nature of the device and other considerations:
Table 12. __cb_monitor__ parameters
return type | method name | method arguments |
|---|---|---|
CaObject | __cb_monitor__ | (CaList object, NatrounCallback callbackObject, CaDict options) |
__cb_monitor__ is similar to some of the features that the BeOS file system offers. It allows an application to register interest in an object, and when anything inside of that object (or the object itself) is modified, the application is notified by way of the Natroun Callback object supplied to __cb_monitor__.
__cb_monitor__ must return a vaild monitor token---used to unregister this monitor---on success or throw an exception on error. A Conformant Natroun Driver must be able to tell the difference between a monitor token and a lock token.
Natroun Callback object may be registered for more than one path. If Natroun Callback object is already registered for exactly this path, __cb_monitor__ must return the original monitor token. Different Callback objects must be able to be supplied for the same path.
Natroun Callback is a class with at least the method:
Table 13. monitor_callback parameters
return type | method name | method arguments |
|---|---|---|
void | monitor_callback | (CaList objects, CaUInt32 event) |
This method will be invoked with a CaList of objects which have been modified. Each object's path is identified by a list itself. The paths of these modified objects must be relative to the Natroun driver's root, which is not the full absolute path of the object.
The argument action gives monitor_callback the event that prompted the callback. If a Conformant Natroun Driver supports __cb_monitor__ the Conformant Natroun Driver must support all the required events in the following table.
Table 14. Events for monitor_callback
Class | Value | Meaning |
|---|---|---|
required | 1 | The object being monitored was the target of a __cb_put__ operation. |
required | 2 | An object inside of the object being monitored was the target of a __cb_put__ operation. |
required | 4 | The object being monitored was the target of a __cb_delete__ operation. |
required | 8 | An object inside of the object being monitored was the target of a __cb_delete__ operation. |
required if supporting __cb_lock__ | 16 | The lock token being monitored has been granted. |
required if supporting __cb_lock__ | 32 | The lock token being monitored has expired. |
An application may remove the listener by either making the Callback object invalid (for example: if the application hosting the original object disappears and the proxy becomes invalid) or the application removes the monitor using __cb_unmonitor__
If monitor_callback throws an exception during its execution, the monitor must be unregistered by the driver.
The CaDict options allows you to set a few options, such as the recurse-depth of the monitor (how deep to monitor this object's children), and the events which you want.
Table 15. Options for __cb_monitor__
Name | Type | Meaning | Default |
|---|---|---|---|
recurse-depth | CaInt32 | Specifies the number of children deep to monitor. A depth of 0 monitors only changes to this object, not to anything contained in it. | 2,147,483,647 |
event-mask | CaUInt32 | A bitmask of the events for which one wants to receive notifications. These events should be OR'd together from the values in the event table above. | 4,294,967,295 (full bitset, all events) |
Table 16. __cb_unmonitor__ parameters
return type | method name | method arguments |
|---|---|---|
void | __cb_unmonitor__ | (CaObject monitor |
__cb_unmonitor__ removes the monitor named by the monitor token.
__cb_unmonitor__ must throw an exception on error. On success __cb_unmonitor__ must just return nothing.
Table 17. __cb_lock__ parameters
return type | method name | method arguments |
|---|---|---|
CaDict | __cb_lock__ | (CaList object, CaInt32 method, CaDateTime timeout) |
Manipulates a lock for an object. The type of object and the value of type determines the exact operation. object must either be a CaList to supply a path or a CaBinary to supply a lock token.
Table 18. Lock Operations
Operation | Value for method | Meaning of object |
|---|---|---|
Obtain Exclusive Lock | -2 | Path or Token |
Obtain Update Lock | -1 | must be a path only |
Refresh Token | 0 | must be a token only |
Obtain Shared Lock | 1 | Path or token |
An Update lock ensures that the caller can upgrade to an Exclusive lock at a later point in time. An Update lock must not be granted unless it will always be possible to upgrade it to an Exclusive lock at a subsequent point in time. If it is possible that the Update lock cannot be upgraded to an Exclusive lock at a subsequent point, the driver must not grant the Update lock request.
All locks must have a timeout. After the timeout has expired, the lock may be released automatically by the driver. This includes locks that are pending but have not yet been granted. The timeout is advisory; applications must expect to get back a different value than they provide. This allows the Natroun driver to set and enforce reasonable values. A time very far in the future (for example, a few years) may be used for "infinite" time locks.
__cb_lock__ method must never block. Should the lock not be grantable at the present time (perhaps because it is held by another user or task), the driver must give out a token and return a wait status. The token must be placed in a queue and granted after the resource becomes available. Should the token expire prior to the lock being granted it, it may be removed from the wait queue. It must not be necessary for an application to "poll" the driver through __cb_lock__ in order to actually upgrade a token in wait status to a token in locked status.
An application may use refresh to reset the timeout of a lock token, to discover if the lock has expired, or to check if the lock has been granted yet by the driver.
The return value of __cb_lock__ must be of type CaDict with the following required members.
Table 19. __cb_lock__ Return Format
Name | Type | Meaning |
|---|---|---|
status | CaInt32 | Status of lock token |
token | CaBinary | Opaque lock token |
timeout | CaDateTime/para> | Time lock expires |
error_message | CaString | Description of error (only provided on error condition) |
Depending on the result of the specified operation, __cb_lock__ should return a particular condition.
Table 20. Lock Conditions and Status Codes
Condition | Reason Condition Arises | Token ('token') | Timeout ('timeout') | Status ('status') |
|---|---|---|---|---|
success | lock was granted, updated or refreshed | the (possibly new) lock token | the actual timeout value used | 0 |
wait | resource already locked, must wait | lock token (must be placed on wait queue) | the actual timeout value used | 1 |
failure | object did not exist, not enough lock resources available, etc. | not returned | not returned | -1 |
invalid lock token | lock token supplied has expired or is not valid | not returned | not returned | -2 |
The driver may return a different lock token than what the application passed as an argument. If the object is accessible through more than one path name, all of those paths must share the the same set of locks and tokens.
Lock tokens must be unique over a very long period of time, as well as unique across all objects during that timespan. Two tokens generated at the same time by different machines on the Internet must generate different tokens. Tokens may be 256 bits. The Casbah Project suggests 128 bit tokens. Tokens could be generated, for example, by using the MAC address of the host, the IP address of the host, and a timestamp, plus some unique information identifying the resource. The exact algorithm is left to the Natroun implementor; however, it must generate a unique value.[1]
A driver that supplies __cb_lock__ must also supply __cb_unlock__.
Table 21. __cb_unlock__ parameters
return type | method name | method arguments |
|---|---|---|
CaBoolean | __cb_unlock__ | (CaObject token) |
Releases the lock held by token. Conformant Natroun Drivers must grant any locks that are blocked on the waiting list. For example: if the token being unlocked was representing Exclusive lock lock, and there are Read locks waiting, the Read locks should be granted. Token should not be valid after an __cb_unlock__ operation.
A driver that implements __cb_lock__ must implement __cb_unlock__. If __cb_lock__ is not implemented, __cb_unlock__ is not required.
| [1] | See http://casbah.org/cbRFC/misc/draft-leach-uuids-guids-01.txt. |