server.h File Reference

#include <stdint.h>

Data Structures
struct	Key
struct	Record
Defines
#define	MAX_PAYLOAD_LEN   100
#define	MAX_VARCHAR_LEN   128
Typedefs
typedef IdxState	IdxState
typedef TxnState	TxnState
typedef enum ErrCode	ErrCode
typedef enum KeyType	KeyType
Enumerations
enum	ErrCode
enum	KeyType
Functions
ErrCode	create (KeyType type, char *name)
ErrCode	openIndex (const char *name, IdxState **idxState)
ErrCode	closeIndex (IdxState *idxState)
ErrCode	beginTransaction (TxnState **txn)
ErrCode	abortTransaction (TxnState *txn)
ErrCode	commitTransaction (TxnState *txn)
ErrCode	get (IdxState *idxState, TxnState *txn, Record *record)
ErrCode	getNext (IdxState *idxState, TxnState *txn, Record *record)
ErrCode	insertRecord (IdxState *idxState, TxnState *txn, Key *k, const char *payload)
ErrCode	deleteRecord (IdxState *idxState, TxnState *txn, Record *record)

---

Define Documentation

#define MAX_PAYLOAD_LEN   100

Specifies the maximum size for a payload.

#define MAX_VARCHAR_LEN   128

Specifies the maximum size for a varchar key.

---

Typedef Documentation

typedef enum ErrCode ErrCode

Status messages for outcomes of API calls.

typedef struct IdxState IdxState

Implementation-specific data stored in this variable, used to identify a thread's state

typedef enum KeyType KeyType

Three possible key types.

typedef struct TxnState TxnState

Implementation-specific data stored in this variable, used to identify a transaction across Indices and store any information necessary for the implementation.

---

Enumeration Type Documentation

enum ErrCode

Status messages for outcomes of API calls. Enumeration values: SUCCESS  DB_DNE  DB_EXISTS  DB_END  KEY_NOTFOUND  TXN_EXISTS  TXN_DNE  ENTRY_EXISTS  ENTRY_DNE  DEADLOCK  FAILURE

enum KeyType

Three possible key types. Enumeration values: SHORT  INT  VARCHAR

---

Function Documentation

ErrCode abortTransaction (  TxnState *  txn  )

Forces the current transaction to abort, rolling back all changes made during the course of the transaction. Parameters: txn  The state variable for the transaction being aborted. Returns: ErrCode SUCCESS if successfully aborted transaction. TXN_DNE if there was no transaction to abort. DEADLOCK if the abort failed because of deadlock. FAILURE if could not abort transaction for some other reason.

ErrCode beginTransaction (  TxnState **  txn  )

Signals the beginning of a transaction. Each thread can have only one outstanding transaction running at a time. Parameters: txn  Returns the transaction state for the new transaction. Returns: ErrCode SUCCESS if successfully began transaction. TXN_EXISTS if there is already a transaction begun for this thread. DEADLOCK if this transaction had to be aborted because of deadlock. FAILURE if could not begin transaction for some other reason.

ErrCode closeIndex (  IdxState *  idxState  )

Terminate use of current index by this thread. Parameters: idxState  The state variable for the index being closed Returns: ErrCode SUCCESS if succesfully closed index. DB_DNE is the DB never existed or was already closed by someone else. FAILURE if could not close DB for some other reason.

ErrCode commitTransaction (  TxnState *  txn  )

Signals the end of the current transaction, committing all changes created in the transaction. Parameters: txn  The state variable for the transaction being committed. Returns: ErrCode SUCCESS if successfully ended transaction. TXN_DNE if there was no transaction currently open. DEADLOCK if this transaction could not be closed because of deadlock. FAILURE if could not end transaction for some other reason.

ErrCode create (  KeyType  type, char *  name )

Creates a new index data structure to be used by any thread. Parameters: type  specifies what type of key the index will use name  a unique name to be used to identify this index in any process Returns: ErrCode SUCCESS if successfully created index. DB_EXISTS if index with specified name already exists. FAILURE if could not create index for some other reason.

ErrCode deleteRecord (  IdxState *  idxState, TxnState *  txn, Record *  record )

Remove the record associated with the given key from the index structure. If a payload is specified in the Record, then the key/payload pair specified is removed. Otherwise, the payload pointer is a length 0 string and all records with the given key are removed from the database. If this is called from outside of a transaction, it should commit immediately. Parameters: idxState  The state variable for this thread txn  The transaction state to be used (or NULL if not in a transaction) record  Record struct containing a Key and a char* payload (or NULL pointer) describing what is to be deleted Returns: ErrCode SUCCESS if successfully deleted record from DB. ENTRY_DNE if the specified key/payload pair could not be found in the DB. KEY_NOTFOUND if the specified key could not be found in the DB, with only the key specified. DEADLOCK if this call could not complete because of deadlock. FAILURE if could not delete record for some other reason.

ErrCode get (  IdxState *  idxState, TxnState *  txn, Record *  record )

Retrieve the first record associated with the given key value; if more than one record exists with this key, return the first record with this key. Contents of the retrieved record are copied into the user supplied Record structure. Records with the same key may be returned in any order, but it must be that if there are n records with the same key k, a call to get followed by n-1 calls to getNext will return all n records with key k. If get returns KEY_NOTFOUND for a key k, the caller may invoke getNext to find the first key after key k. Parameters: idxState  The state variable for this thread txn  The transaction state to be used (or NULL if not in a transaction) record  Record containing the key being retrieved, into which the payload is copied. Returns: ErrCode SUCCESS if successfully retrieved and returned unique record. KEY_NOTFOUND if specified key value was not found in the DB. DEADLOCK if this call could not complete because of deadlock. FAILURE if could not retrieve unique record for some other reason.

ErrCode getNext (  IdxState *  idxState, TxnState *  txn, Record *  record )

Retrieve the record following the previous record retrieved by get or getNext. If no such call has occurred since the current transaction began, or if this is called from outside of a transaction, this returns the first record in the index. Records are ordered in ascending order by key. Records with the same key but different payloads may be returned in any order. If get returned KEY_NOT_FOUND for a key k, invoking getNext will return the first key after k. If the index is closed and reopened, or a new transaction has begun since any previous call of get or getNext, getNext returns the first record in the index. Parameters: idxState  The state variable for the index whose next Record is to be returned txn  The transaction state to be used (or NULL if not in a transaction) record  Record through which the next key/payload pair is returned Returns: ErrCode SUCCESS if successfully retrieved and returned the next record in the DB. DB_END if reached the end of the DB. DEADLOCK if this call could not complete because of deadlock. FAILURE if could not retrieve next record for some other reason.

ErrCode insertRecord (  IdxState *  idxState, TxnState *  txn, Key *  k, const char *  payload )

Insert a payload associated with the given key. An identical key can be used multiple times, but only with unique payloads. If this is called from outside of a transaction, it should commit immediately. Records in an index are ordered in ascending order by key. Records with the same key may be stored in any order. The implementation is responsible for making a copy of payload (e.g., it may not assume that the payload pointer continues to be valid after this routine returns.) Parameters: idxState  The state variable for this thread txn  The transaction state to be used (or NULL if not in a transaction) k  key value for insert payload  Pointer to the beginning of the payload string Returns: ErrCode SUCCESS if successfully inserted record into DB. ENTRY_EXISTS if identical record already exists in DB. DEADLOCK if this call could not complete because of deadlock. FAILURE if could not insert entry for some other reason.

ErrCode openIndex (  const char *  name, IdxState **  idxState )

Opens a specific index data structure to be used by this thread. Parameters: name  the unique name specifying the index being opened idxState  returns the state handle for the index being opened Returns: ErrCode SUCCESS if successfully opened index. DB_DNE if the name given does not have an associated DB that has been create()d. FAILURE if DB exists but could not be opened for some other reason.

---