Functions
int	fastbit_iapi_attach_full_index (const char , double , uint64_t, int64_t , uint64_t, uint32_t , uint64_t)
	Attach an index to a column already registered. More...

int	fastbit_iapi_attach_index (const char , double , uint64_t, int64_t , uint64_t, void , FastBitReadBitmaps)
	Attach an index to a column already registered. More...

int	fastbit_iapi_build_index (const char , const char )
	Build index. More...

int	fastbit_iapi_deconstruct_index (const char , double keys, uint64_t nkeys, int64_t *offsets, uint64_t noffsets, uint32_t *bms, uint64_t nbms)
	Write index into three arrays. More...

int	fastbit_iapi_extend_array (const char , FastBitDataType, void , uint64_t)
	Extend the array with the given name with new content. More...

int	fastbit_iapi_extend_bit_array_with_selection (const char *, FastBitSelectionHandle)
	Extend the array with the given name with new content. More...

void	fastbit_iapi_free_all ()
	Free all cached object for IAPI. More...

void	fastbit_iapi_free_array (const char *)
	Remove an array from the list of known variables. More...

void	fastbit_iapi_free_array_by_addr (void *)
	Remove an array from the list of known variables. More...

int64_t	fastbit_iapi_get_number_of_hits (FastBitIndexHandle, uint32_t, uint32_t, uint32_t *)
	Retrieve the numbers of values in the given range. More...

FastBitIndexHandle	fastbit_iapi_reconstruct_index (double , uint64_t, int64_t , uint64_t)
	Reconstitute the index data structure from the first two arrays produced by fastbit_iapi_write_index. More...

int	fastbit_iapi_register_array (const char , FastBitDataType, void , uint64_t)
	Register a simple array under the specified name. More...

int	fastbit_iapi_register_array_ext (const char , FastBitDataType, uint64_t , uint64_t, void *, FastBitReadExtArray)
	Register an external array under the specified name. More...

int	fastbit_iapi_register_array_index_only (const char , FastBitDataType, uint64_t , uint64_t, double , uint64_t, int64_t , uint64_t, void *, FastBitReadBitmaps)
	Register an array under the specified name. More...

int	fastbit_iapi_register_array_nd (const char , FastBitDataType, void , uint64_t *, uint64_t)
	Register a n-dimensional array under the specified name. More...

int	fastbit_iapi_register_selection_as_bit_array (const char *, FastBitSelectionHandle)
	Register query result as a bit array. More...

int	fastbit_iapi_resolve_range (FastBitIndexHandle, FastBitCompareType, double, uint32_t , uint32_t , uint32_t , uint32_t )
	Evalute a range condition on an index data structure. More...

FastBitSelectionHandle	fastbit_selection_combine (FastBitSelectionHandle, FastBitCombineType, FastBitSelectionHandle)
	Combining two selection conditions into one. More...

FastBitSelectionHandle	fastbit_selection_create (FastBitDataType, void , uint64_t, FastBitCompareType, void )
	Create a simple one-sided range condition. More...

FastBitSelectionHandle	fastbit_selection_create_nd (FastBitDataType, void , uint64_t , uint64_t, FastBitCompareType, void *)
	Create a simple one-sided range condition on a n-dimensional array. More...

int64_t	fastbit_selection_estimate (FastBitSelectionHandle)
	Provide an upper bound on the number of hits. More...

int64_t	fastbit_selection_evaluate (FastBitSelectionHandle)
	Compute the number of hits. More...

void	fastbit_selection_free (FastBitSelectionHandle)
	Free/destroy the selection object. More...

int64_t	fastbit_selection_get_coordinates (FastBitSelectionHandle, uint64_t *, uint64_t, uint64_t)
	Extract the coordinates of the elements of arrays satisfying the selection conditions. More...

FastBitSelectionHandle	fastbit_selection_osr (const char *, FastBitCompareType, double)
	Create a simple one-sided range condition. More...

void	fastbit_selection_purge_results (FastBitSelectionHandle)
	Free in-memory resources associated with the selection handle. More...

int64_t	fastbit_selection_read (FastBitDataType, const void , uint64_t, FastBitSelectionHandle, void , uint64_t, uint64_t)
	Fill the buffer (buf) with the next set of values satisfying the selection criteria. More...

Detailed Description

Function Documentation

int fastbit_iapi_attach_full_index	(	const char *	,
		double *	,
		uint64_t	,
		int64_t *	,
		uint64_t	,
		uint32_t *	,
		uint64_t
	)

Attach an index to a column already registered.

Note: The current implementation avoids copying the arrays passed to this function, therefore, these arrays can not be freed until the indexing data structure is cleared with fastbit_iapi_free_all.

int fastbit_iapi_attach_index	(	const char *	,
		double *	,
		uint64_t	,
		int64_t *	,
		uint64_t	,
		void *	,
		FastBitReadBitmaps
	)

Attach an index to a column already registered.

Note: The current implementation avoids copying the arrays passed to this function, therefore, these arrays can not be freed until the indexing data structure is cleared with fastbit_iapi_free_all.

int fastbit_iapi_build_index	(	const char *	aname,
		const char *	iopt
	)

Build index.

aname: column name
iopt: indexing option

Returns 0 for success, a negative number for any error or failure.

Note: If one of nkeys, noffsets or nbitmaps is nil, then none of them will be assigned a value. This is taken as the user does not want to write the index out.

References ibis::column::hasIndex(), and ibis::column::loadIndex().

int fastbit_iapi_deconstruct_index	(	const char *	,
		double **	keys,
		uint64_t *	nkeys,
		int64_t **	offsets,
		uint64_t *	noffsets,
		uint32_t **	bms,
		uint64_t *	nbms
	)

Write index into three arrays.

This function allocates the memory space for three arrays named keys, offsets and bms. The caller is responsible for freeing these three arrays.

References ibis::column::indexWrite(), ibis::array_t< T >::release(), and ibis::array_t< T >::size().

int fastbit_iapi_extend_array	(	const char *	nm,
		FastBitDataType	dtype,
		void *	addr,
		uint64_t	nelm
	)

Extend the array with the given name with new content.

nm: name of the array to be extended.
dtype: type of the array.
addr: address of the new content to be added to the named array.
nelm: number of elements in the new content.

The new content is copied to the existing array resulting a large array. The newly extended array contains a copy of the content in the buffer at addr.

This function returns an integer error code. It returns 0 for success, or a negative number to indicate error of some sort.

References ibis::bord::column::append(), ibis::bitvector::appendByte(), ibis::BIT, ibis::bitvector::set(), ibis::bitvector::size(), and ibis::column::type().

Referenced by fastbit_iapi_extend_bit_array_with_selection().

int fastbit_iapi_extend_bit_array_with_selection	(	const char *	nm,
		FastBitSelectionHandle	h
	)

Extend the array with the given name with new content.

Warning: the selection/query must have been evaluated already, otherwise ther is no bitvector to be used for this function.

References fastbit_iapi_extend_array(), and ibis::bitvector::size().

void fastbit_iapi_free_all ( )

Free all cached object for IAPI.

void fastbit_iapi_free_array ( const char * )

Remove an array from the list of known variables.

void fastbit_iapi_free_array_by_addr ( void * )

Remove an array from the list of known variables.

The given address is that of the data buffer passed to functions fastbit_iapi_register_array and fastbit_iapi_register_array_nd.

int64_t fastbit_iapi_get_number_of_hits	(	FastBitIndexHandle	,
		uint32_t	,
		uint32_t	,
		uint32_t *
	)

Retrieve the numbers of values in the given range.

To be removed. Do not use.

References ibis::bitvector::cnt().

FastBitIndexHandle fastbit_iapi_reconstruct_index	(	double *	,
		uint64_t	,
		int64_t *	,
		uint64_t
	)

Reconstitute the index data structure from the first two arrays produced by fastbit_iapi_write_index.

The 3rd array is larger and is to be read in pieces as needed.

To be removed. Do not use.

int fastbit_iapi_register_array	(	const char *	nm,
		FastBitDataType	dtype,
		void *	buf,
		uint64_t	nelm
	)

Register a simple array under the specified name.

nm name of the array. The array name nm must follow the naming convention specified in the documentation for ibis::column. More specifically, the name must start with a underscore (_) or one of the 26 English alphabets, and the remaining characters in the name must be drawn from _, a-z, A-Z, 0-9, '.', and ':'. Additionally, the column names are used without considering the cases of the letters a-z.

dtype data type.

buf the data buffer. For most data types, this is a raw pointer to data from user. For example, if the type is FastBitDataTypeDouble, buf is of type 'double *'. The exception is when the type is either FastBitDataTypeBitRaw or FastBitDataTypeBitCompressed. When the type is FastBitDataTypeBitRaw, the buffer is expected to be 'unsigned char*', and each bit in the buffer is treated as the literal bits. When the type is FastBitDataTypeBitCompressed, the buffer is expected to 'ibis::bitvector*'.

nelm number of elements of the specified type in the data buffer. When the data type is FastBitDataTypeBitRaw or FastBitDataTypeBitCompressed, nelm refers to the number of bits represented by the content of data buffer.

Returns: This function returns 0 to indicate success, a positive number to indicate that the content has already been registered, a negative number to indicate error such as unknown data type, null string for name or memory allocation error.

Referenced by fastbit_iapi_register_selection_as_bit_array().

int fastbit_iapi_register_array_ext	(	const char *	nm,
		FastBitDataType	dtype,
		uint64_t *	dims,
		uint64_t	nd,
		void *	ctx,
		FastBitReadExtArray	rd
	)

Register an external array under the specified name.

Note: the array name nm must follow the naming convention specified in the documentation for ibis::column. More specifically, the name must start with a underscore (_) or one of the 26 English alphabets, and the remaining characters in the name must be drawn from _, a-z, A-Z, 0-9, '.', and ':'. Additionally, the column names are used without considering the cases of the letters a-z.

int fastbit_iapi_register_array_index_only	(	const char *	nm,
		FastBitDataType	dtype,
		uint64_t *	dims,
		uint64_t	nd,
		double *	keys,
		uint64_t	nkeys,
		int64_t *	offsets,
		uint64_t	noffsets,
		void *	bms,
		FastBitReadBitmaps	rd
	)

Register an array under the specified name.

Note: the array name nm must follow the naming convention specified in the documentation for ibis::column. More specifically, the name must start with a underscore (_) or one of the 26 English alphabets, and the remaining characters in the name must be drawn from _, a-z, A-Z, 0-9, '.', and ':'. Additionally, the column names are used without considering the cases of the letters a-z.

int fastbit_iapi_register_array_nd	(	const char *	nm,
		FastBitDataType	dtype,
		void *	buf,
		uint64_t *	dims,
		uint64_t	nd
	)

Register a n-dimensional array under the specified name.

Note: the array name nm must follow the naming convention specified in the documentation for ibis::column. More specifically, the name must start with a underscore (_) or one of the 26 English alphabets, and the remaining characters in the name must be drawn from _, a-z, A-Z, 0-9, '.', and ':'. Additionally, the column names are used without considering the cases of the letters a-z.

int fastbit_iapi_register_selection_as_bit_array	(	const char *	nm,
		FastBitSelectionHandle	h
	)

Register query result as a bit array.

Warning: the selection/query must have been evaluated already, otherwise ther is no bitvector to be used for this function.

References fastbit_iapi_register_array(), and ibis::bitvector::size().

int fastbit_iapi_resolve_range	(	FastBitIndexHandle	ih,
		FastBitCompareType	ct,
		double	cv,
		uint32_t *	cand0,
		uint32_t *	hit0,
		uint32_t *	hit1,
		uint32_t *	cand1
	)

Evalute a range condition on an index data structure.

To be removed. Do not use.

ih: the index handle.
ct: comparision operator.
cv: query boundary, the value to be compared.
cand0: left-most bin that might have some hits.
hit0: left-most bin that are definitely all hits.
hit1: right-most bin that are definitely all hits.
cand1: right-most bin that are possible hits.

References ibis::index::BINNING, ibis::index::RELIC, and ibis::index::type().

FastBitSelectionHandle fastbit_selection_combine	(	FastBitSelectionHandle	h1,
		FastBitCombineType	cmb,
		FastBitSelectionHandle	h2
	)

Combining two selection conditions into one.

Note: The new object take ownership of the two incoming expressions. This arrangement allows the user to delete the last object produced to free all objects going into building the last combined object.

References ibis::qExpr::setLeft(), and ibis::qExpr::setRight().

FastBitSelectionHandle fastbit_selection_create	(	FastBitDataType	dtype,
		void *	buf,
		uint64_t	nelm,
		FastBitCompareType	ctype,
		void *	bound
	)

Create a simple one-sided range condition.

To be removed. Do not use.

Create a simple one-sided range condition.

This function registers the incoming array as ibis::bord::column object.

It returns a nil value in case of error.

References ibis::column::name(), and ibis::qExpr::setLeft().

FastBitSelectionHandle fastbit_selection_create_nd	(	FastBitDataType	dtype,
		void *	buf,
		uint64_t *	dims,
		uint64_t	nd,
		FastBitCompareType	ctype,
		void *	bound
	)

Create a simple one-sided range condition on a n-dimensional array.

To be removed. Do not use.

Create a simple one-sided range condition on a n-dimensional array.

This function registers the incoming array as ibis::bord::column object.

It returns a nil value in case of error.

References ibis::column::name(), and ibis::qExpr::setLeft().

int64_t fastbit_selection_estimate ( FastBitSelectionHandle h )

Provide an upper bound on the number of hits.

There is no guarantee on how accurate is the estimation. This estimation may be sufficient for the purpose of allocating workspace required for reading the selection.

References ibis::bitvector::cnt(), and ibis::countQuery::setWhereClause().

int64_t fastbit_selection_evaluate ( FastBitSelectionHandle h )

Compute the number of hits.

This function performs the exact evaluation and store the results in a global data structure.

Note: The precise evaluation needs to be performed before reading the data values. If it is not performed, the read selection function will perform the precise evaluation.

References ibis::bitvector::cnt(), and ibis::countQuery::setWhereClause().

Referenced by fastbit_selection_get_coordinates(), and fastbit_selection_read().

void fastbit_selection_free ( FastBitSelectionHandle h )

Free/destroy the selection object.

Only the top most level of the object hierarchy, i.e., the last selection handle return by the combine operations, needs to be freed.

int64_t fastbit_selection_get_coordinates	(	FastBitSelectionHandle	h,
		uint64_t *	buf,
		uint64_t	nbuf,
		uint64_t	skip
	)

Extract the coordinates of the elements of arrays satisfying the selection conditions.

h the query handle.
buf buffer to carry the output coordinates.
nbuf number of elements in the given buffer.
skip number of selected points to be skip before the coordinates are placed in buf. This is necessary if the incoming buffer is too small to hold all the points and the caller has to invoke this function repeatedly.

The shape of the array is determined by shape of the array in the first (left-most) selection condition tree. The implicit assumption is that all arrays/variables involved in the selection conditions have the same shape.

References fastbit_selection_evaluate(), and ibis::array_t< T >::size().

FastBitSelectionHandle fastbit_selection_osr	(	const char *	aname,
		FastBitCompareType	ctype,
		double	bound
	)

Create a simple one-sided range condition.

It returns a nil value in case of error.

References ibis::qExpr::setLeft().

void fastbit_selection_purge_results ( FastBitSelectionHandle )

Free in-memory resources associated with the selection handle.

int64_t fastbit_selection_read	(	FastBitDataType	dtype,
		const void *	base,
		uint64_t	nbase,
		FastBitSelectionHandle	h,
		void *	buf,
		uint64_t	nbuf,
		uint64_t	start
	)

Fill the buffer (buf) with the next set of values satisfying the selection criteria.

Both nbase and nbuf are measured in number of elements of the specified type, NOT in bytes.

The start position is measuremeted as positions in the list of selected values, not positions in the base data.

The return value is the number of elements successfully read. In case of error, a negative value is returned.

References fastbit_selection_evaluate().



	Contact us Disclaimers FastBit source code FastBit mailing list archive

Functions

Detailed Description

Function Documentation