Internet Backplane Protocol: API 1.0
Alessandro Bassi, Micah D. Beck, James S. Plank, Rich Wolski · 2001
In this document, we present a description of the IBP version 1.0 API. The current implementation of IBP supports only synchronized client requests; all client IBP calls will block pending completion on the server(s) side, or the expiration of the client’s timeout. We present the C-language prototype of every call along with a detailed description of the data structures, success behavior and error conditions involved in that call. Failure of an IBP client call is indicated by a return value of 0, or NULL, with a special variable (IBP errno) set to the appropriate error code. 1 IBP Data Structures A few data structures are used through the IBP world. 1.1 IBP capability This is the basic building block of IBP. Its format is: ibp://hostname:port/key/WRMKey/WRM hostname:port The two above fields are also called IBP depot: variable name variable type host char * port int This table is pretty self-explaining. key The key can be roughly considered to be the filename. WRMKey The WriteKey/ ReadKey/ ManageKey is a value that allows the access to the right key for writing, reading, and managing. WRM This field can have only three values, and is linked to the field above. The values are: – WRITE – READ – MANAGE 1.2 Various tables 1.2.1 IBP attributes variable name variable type duration time t reliability int type int duration : specifies the time at which the allocated storage area will be automatically purged from the pool of storage areas managed by the server. Time is specified in seconds since the epoch (as returned by UNIX’s time(2) function). A value of 0 indicates permanent status for the allocated storage area (it’ll be only purged when no more clients have read access to it, otherwise it will be kept alive according to the reliability property). reliability : is a flag that determines how reliable the allocated storage area will be. The current version of IBP supports two levels of reliability: – IBP STABLE which guarantees the existence of the allocated storage area until it is removed due to lack of readers as explained above. – IBP VOLATILE which declares the allocated area to be volatile, in the sense that the corresponding IBP server can reclaim storage allocated to this area whenever site administration and/or IBP server policy mandates such move. Stable storage is never reclaimed by IBP server as long as at least one client has read access to that storage. type is a flag that determines the type of storage allocated. The current version of IBP supports four types of storage: – IBP BYTEARRAY which treats the allocated area as a flat byte array. This will have the following implications on future accesses to that storage area: Requests for read to the allocated area will be denied if there are not enough data to satisfy the read request at the time the request is received by the IBP server. Requests to write (append) to the allocated area will be denied if it leads to the total size of the storage area exceeding the maximum allowable size specified in size. A maximum of one write operation can be actively writing to the storage area at any given time; other write requests received by the server are queued pending completion of the running write process. No limit is imposed on the number of simultaneous read accesses to the storage area. In addition, due to the use of append-only semantics for write operations, a write operation can be simultaneously active with anynumber of read operations to the same storage area. – IBP FIFO which causes the allocated storage area to be treated as a FIFO queue, with the following implications: Read data is removed from storage area once read. Read requests will be blocked if not enough un-readdata is available in the storage area. In addition, noupper limit is placed on the size of data in read requests. Write requests will be blocked if there is not enough space in the storage area to complete the write operation. In addition, there is no upper limit on the size of data involved in a write operation to the storage area. Blocked operations will be un-blocked only when there is more data to read (blocked read operation) or available space to write (blocked write operations) A maximum of one write operation and one read operation can be simultaneously active at any given time. Further requests are blocked pending completion of running operations. – IBP CIRQ which causes the allocated storage area to be treated as a Circular Queue, with the following implications: Read data is removed from storage area once read. Read requests will be blocked if not enough un-readdata is available in the storage area. In addition, noupper limit is placed on the size of data in read requests. Write requests will NOT be blocked if there is not enough space in the storage area to complete the write operation, but will overwrite the beginning of the queue. In addition, there is no upper limit on the size of data involved in a write operation to the storage area. Blocked operations will be un-blocked only when there is more data to read (blocked read operation). A maximum of one write operation and one read operation can be simultaneously active at any given time. Further requests are blocked pending completion of running operations. – IBP BUFFER which causes the allocated storage area to be treated as a restricted-access flat storage area, with the following properties: Only one process can be actively accessing the storage area for read and/or write operation at any given time. Other requests are blocked pending completion of theone that has access to the storage area at any giventime. All write operations start at the beginning of the storage area, overwriting any data that had been stored there previously (even if it had not been read). The amount of data available to a read operation at any given time is the amount that had been stored by the last write call. 1.2.2 IBP set of caps variable name variable type readCap IBP cap writeCap IBP cap manageCap IBP cap The capabilities included in an IBP set of caps object allow the client read access, write access, and management access to a particular storage area, respectively. 1.2.3 IBP CapStatus variable name variable type readRefCount int writeRefCount int currentSize int maxSize ulong t attrib IBP attributes readRefCount and writeRefCount hold the reference count for the read and write capabilities respectively (on return from an IBP PROBE command) and are ignored for the other IBP manage() commands. currentSize holds the current size of data stored in the underlying storage area (for storage areas of type IBP FIFO and IBP CIRQ it holds the maximum size of the underlying storage area). maxSize holds the maximum size of the storage area, while attrib holds the storage area attributes as defined earlier. 1.2.4 IBP DptStatus variable name variable type StableStor ulong t StableStorUsed ulong t VolStore ulong t VolStoreUsed ulong t duration long StableStor and VolStor are the Stable Storage size and the Volatile Storage size respectively, while StableStorUsed and VolStorUsed are the Stable Storage used and the Volatile Storage used. The Duration parameter is the max duration. 1.2.5 IBP timer variable name variable type ClientTimeout int ServerSync int The two timers have a completely different function. The ClientTimeout indicates the time the application is willing to wait for a response from the server. This parameter is used to improve the fault-tolerance of the IBP Client Library, to prevent waiting forever from an answer from a hanged server; or in case the network connection is particularely bad, or a very high latency time. The ServerSync is used as an ”or” condition: i.e., in a IBP load operation, the application program can ask for N bytes or whatever gathered after ServerSync time. This can be very helpful when another client is writing on the same media, and the application asking to load the data does not know how many bytes are written, but it’s willing to wait for some time before giving up.