#ifndef ICE_TOKEN_H #define ICE_TOKEN_H module IceToken { /** * An Enum representing the type of Token **/ enum TokenType { RemoteMutexType, RemoteRLockType, RemoteWLockType }; /** * An interface for acquiring, renewing, and releasing a distributed * synchronization token. It offers recursive * acquisition, FIFO waiter ordering, and deadlock detection. It * depends on the Token Server for its distributed synchronization * semantics. * **/ interface Token { /** * Acquire the distributed token. * * @param notify. If set to 1 and the token is already held, the owner * is notified. * @param timeout. Timeout (in milli seconds) value for the acquire call * is kept at the token server. * @return 0 on success, -1 on failure. **/ int acquire (bool notify, long timeout); /** * Try to acquire the distributed token. If the token is already * held, the call returns without queueing the caller as a waiter. * * @return 0 on success (the token was acquired), and -1 if the token * was already held. **/ int tryacquire (); /** * Renew the token by offering to release it if there are any other * waiters, otherwise get the token back immediately. * This operation equivalent to followed by , but * it is faster. * * @param newPosition If there are waiters and newPosition == -1, the * caller is queued at the rear of the waiter list. Otherwise, * newPosition specifies the number of waiters to "let by" * before reacquiring the token (effectively, the position in the * waiter list.) * @param timeout. Timeout (in milli seconds) value for the acquire call * is kept at the token server. * @return 0 on success, -1 on failure. **/ int renew (int newPosition, long timeout); /** * Release the distributed token. If the caller is not the owner, it * is removed from the waiter list (if applicable.) * * @param timeout. Timeout (in milli seconds) value for the release call * is kept at the token server. * @return 0 on success, -1 on failure **/ int release (long timeout); /** * @return The client id of the current token holder **/ string ownerId (); nonmutating Token* clone (); }; /** * * Mapping of token name to token proxy. * **/ dictionary TokenDict; /** * * This exception indicates that an attempt was made to create a token * that already exists. * **/ exception TokenExists { /** * * The name of the token that already exists. * */ string name; }; /** * * This exception indicates that an attempt was made to retrieve a * token that does not exist. * **/ exception NoSuchToken { /** * * The name of the token that does not exist. * **/ string name; }; /** * * A token manager manages tokens, and subscribers to tokens. * * @see Token * **/ interface TokenManager { /** * * Create a new token. The token name must be unique, otherwise * [TokenExists] is raised. * * @param name The name of the token. * @param type The supported types are "RemoteMutex", "RemoteRLock" and * "RemoteWLock". * * @return A proxy to the token instance of specific type. * * @throws TokenExists Raised if a token with the same name already * exists. * **/ Token* create(string name, TokenType type) throws TokenExists; /** * * Retrieve a token by name. * * @param name The name of the token. * * @return A proxy to the token instance. * * @throws NoSuchToken Raised if the token does not exist. * **/ nonmutating Token* retrieve(string name, TokenType type) throws NoSuchToken; /** * * Retrieve all tokens of type "type" managed by this token manager. * * @param Enum to identify the token type * @return A dictionary of string, token proxy pairs. * **/ nonmutating TokenDict retrieveAll(TokenType type); }; /** * RemoteMutex offers methods for acquiring, renewing, and * releasing a distributed synchronization mutex. Similar to * Token, it offers recursive acquisition, FIFO waiter ordering, * and deadlock detection. It depends on the Token Server for its * distributed synchronization semantics. **/ interface RemoteMutex extends Token { }; /** * Interface for acquiring, renewing, and releasing a distributed * readers lock. * * Multiple readers can hold the lock simultaneously when no writers have * the lock. Alternatively, when a writer holds the lock, no other * participants (readers or writers) may hold the lock. * It depends on the Token Server for its distributed synchronization * semantics. **/ interface RemoteRLock extends Token { }; /** * Interface for acquiring, renewing, and releasing a distributed * writers lock. * **/ interface RemoteWLock extends Token { }; /** * * TokenCollenction offers and interface for performing operations on group * of token as a whole. * **/ interface TokenCollenction extends Token { /** * Insert a Token into the collection. * @param which needs to be added to the collection. * @return returns 0 on success, -1 on failure. If the * proxy already exists in the collection with the same name, the * insertion will fail. */ int insert (Token* tokenProxy); /** * removes the Token matching the given from the * collection. On success, extract returns 0. * @return On failure (tokenName was not in the collection,) extract returns * -1. On success, the token proxy is returned.. */ Token* extract (string tokenName); /// @return returns the proxy if true. 0 otherwise. Token* isMember (string tokenName); /** * @param token proxy for which the membership is to be verified * @return 1 if the specified token in the collection else 0 */ int isMemberProxy (Token* tokenProxy); }; }; #endif