server.h File Reference

#include <stdint.h>

Data Structures
struct	Key
struct	Record

Macros
#define	MAX_PAYLOAD_LEN   100
#define	MAX_VARCHAR_LEN   128

Typedefs
typedef struct IdxState	IdxState
typedef struct 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)

Macro Definition Documentation

MAX_PAYLOAD_LEN

#define MAX_PAYLOAD_LEN   100

Specifies the maximum size for a payload.

MAX_VARCHAR_LEN

#define MAX_VARCHAR_LEN   128

Specifies the maximum size for a varchar key.

Typedef Documentation

ErrCode

typedef enum ErrCode ErrCode

Status messages for outcomes of API calls.

IdxState

typedef struct IdxState IdxState

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

KeyType

typedef enum KeyType KeyType

Three possible key types.

TxnState

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

ErrCode

enum ErrCode

Status messages for outcomes of API calls.

Enumerator
SUCCESS
DB_DNE
DB_EXISTS
DB_END
KEY_NOTFOUND
TXN_EXISTS
TXN_DNE
ENTRY_EXISTS
ENTRY_DNE
DEADLOCK
FAILURE

KeyType

enum KeyType

Three possible key types.

Enumerator
SHORT
INT
VARCHAR

Function Documentation

abortTransaction()

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.

beginTransaction()

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.

closeIndex()

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.

commitTransaction()

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.

create()

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.

deleteRecord()

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.

get()

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.

getNext()

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.

insertRecord()

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.

openIndex()

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.