/*
 * Header file for skip lists.
 *
 * Copyright 1996 by Gray Watson.
 *
 * $Id: skip.h,v 1.2 1998/03/25 01:07:02 gray Exp $
 */

/*
 * Based on the Skip List algorithms described in the June 1990 issue
 * of CACM and invented by William Pugh in 1987.
 */

#ifndef __SKIP_H__
#define __SKIP_H__

typedef int	(*skip_compare_t)(const void *data1, const int size1,
				  const void *data2, const int size2);

/* skip list error codes - need to be above skip_loc inclusion */
#define SKIP_ERROR_NONE		1	/* no error from function */
#define SKIP_ERROR_PNT		2	/* bad skip pointer */
#define SKIP_ERROR_ARG_NULL	3	/* buffer args were null */
#define SKIP_ERROR_SIZE		4	/* size of data was bad */
#define SKIP_ERROR_OVERWRITE	5	/* key exists and we cant overwrite */
#define SKIP_ERROR_NOT_FOUND	6	/* key does not exist */
#define SKIP_ERROR_ALLOC	7	/* memory allocation error */
#define SKIP_ERROR_LINEAR	8	/* no linear access started */
#define SKIP_ERROR_FILE		9	/* could not open file */
#define SKIP_ERROR_INTERNAL	10	/* found inconsistancy with list */
#define SKIP_ERROR_MMAP_NONE	11	/* no mmap support */
#define SKIP_ERROR_MMAP		12	/* could not mmap file */
#define SKIP_ERROR_MMAP_OP	13	/* can't perform operation on mmap */

#ifdef SKIP_MAIN

#include "skip_loc.h"

#else

/* generic skip type */
typedef	void	skip_t;

#endif

/*<<<<<<<<<<  The below prototypes are auto-generated by fillproto */

/*
 * alloc and return a new skip list.  the COMPARE function is used to
 * locate keys -- set to null to use memcmp.  COMPARE should return
 * effectively (*key1) - (*key2) (<0,==0,>0 for (*key1) <,==,>
 * (*key2)).  returns null on error and passes back skip error codes
 * in ERROR_P.
 */
extern
skip_t	*skip_alloc(const skip_compare_t compare, int *error_p);

/*
 * clear the SKIP_P structure.  returns skip error codes.
 */
extern
int	skip_clear(skip_t *skip_p);

/*
 * clear and free the SKIP_P structure.  returns skip error codes.
 */
extern
int	skip_free(skip_t *skip_p);

/*
 * Add a key(KEY_BUF, KEY_SIZE) data(DATA_BUF, DATA_SIZE) pair to
 * SKIP_P.  OVERWRITE, if not 0, will allow the overwriting of data
 * already in the list.  The data and key data will be copied in from
 * the _BUF pointers and stored in skip buffers.  If you pass in a int
 * as data, the int will be copied into the skip entry.  Set either
 * _SIZE < 0 to do internal strlen.
 *
 * If DATA_BUF is null, it will allocate and and store a random block of
 * bytes of DATA_SIZE.  If DATA_BUF is null and DATA_SIZE is 0 then it
 * will store a null pointer as the data.  If BUF_P is not null then
 * it will pass back the block that it allocated for the data.  If
 * OVERWRITE is 0, and the key exists, BUF_P will contain the data
 * associated with that key and a overwrite error will be returned.
 * It returns skip error codes.
 */
extern
int	skip_insert(skip_t *skip_p,
		    const void *key_buf, const int key_size,
		    const void *data_buf, const int data_size,
		    void **buf_p, const char overwrite);

/*
 * find in SKIP_P, KEY of size KEY_SIZE returning pointer to data in
 * DATA_P and size in DATA_SIZE_P (if either not null).  any size arg
 * can be < 0 meaning that it will do a strlen on them.  returns skip
 * error codes.
 */
extern
int	skip_retrieve(skip_t *skip_p,
		      const void *key_buf, const int key_size,
		      void **data_p, int *data_size_p);

/*
 * Delete from SKIP_P, KEY of size KEY_SIZE with its associated data.
 * any size arg can be < 0 meaning that it will do a strlen on them.
 * If DATA_BUF is not null, it will get the allocated space of the
 * data which must be freed.  If DATA_SIZE is not null, it will get
 * the data's size.  Returns skip error codes.
 */
extern
int	skip_delete(skip_t *skip_p, const void *key_buf, const int key_size,
		    void **data_buf, int *data_size_p);

/*
 * Delete the first entry from SKIP_P.  It passes back the KEY_P
 * (which will need to be freed later) and size KEY_SIZE_P with its
 * DATA_P (which also must then be freed) and size DATA_SIZE_P, if any
 * non-null.  Returns skip error codes.
 */
extern
int	skip_delete_first(skip_t *skip_p,
			  void **key_p, int *key_size_p,
			  void **data_p, int *data_size_p);

/*
 * Get some information about SKIP_P.  It passes back the height of
 * the current skip-node in HEIGHT_P.  Returns skip error codes.
 */
extern
int	skip_info(skip_t *skip_p, int *height_p);

/*
 * redo the height of all entries in SKIP_P to be of optimal height.
 * returns skip error codes.
 */
extern
int	skip_normalize(skip_t *skip_p);

/*
 * return the string equivalent of skip ERROR
 */
extern
const char	*skip_strerror(const int error);

/*
 * Return the size of the skip_t type.
 */
extern
int	skip_type_size(void);

/*
 * get from SKIP_P, the first KEY_P and size KEY_SIZE_P with its DATA_P
 * and size DATA_SIZE_P (if any non-null).  returns skip error codes.
 */
extern
int	skip_first(skip_t *skip_p,
		   void **key_p, int *key_size_p,
		   void **data_p, int *data_size_p);

/*
 * get from SKIP_P, the next KEY_P and size KEY_SIZE_P with its DATA_P and
 * size DATA_SIZE_P (if any non-null). returns skip error codes.
 */
extern
int	skip_next(skip_t * skip_p,
		  void **key_p, int *key_size_p,
		  void **data_p, int *data_size_p);

/*
 * get from SKIP_P, the current KEY_P and size KEY_SIZE_P with its DATA_P
 * and size DATA_SIZE_P (if any non-null). returns skip error codes.
 */
extern
int	skip_this(skip_t *skip_p,
		  void **key_p, int *key_size_p,
		  void **data_p, int *data_size_p);

/*
 * mmap a skip from disk at PATH.  The COMPARE function is used to
 * locate keys and should match (exactly) the routine used to build
 * the list that was written -- set to null to use memcmp.  Returns a
 * skip pointer or NULL on error.  Passes back skip errors in ERROR_P.
 */
extern
skip_t	*skip_mmap(const char *path, const skip_compare_t compare,
		   int *error_p);

/*
 * unmap a skip SKIP_P from memory.  returns skip error codes.
 */
extern
int	skip_munmap(skip_t *skip_p);

/*
 * Reads and returns a skip from PATH.  The COMPARE function is used
 * to locate keys and should match (exactly) the routine used to build
 * the list that was written -- set to null to use memcmp.  Passes
 * back skip errors in ERROR_P.
 */
extern
skip_t	*skip_read(const char *path, const skip_compare_t compare,
		   int *error_p);

/*
 * write skip in SKIP_P to file PATH with file perms MODE
 */
extern
int	skip_write(const skip_t *skip_p, const char *path, const int mode);

/*<<<<<<<<<<   This is end of the auto-generated output from fillproto. */

#endif /* ! __SKIP_H__ */