#include "flat_file_types.h"
#include "flat_file.h"

Description

Function declarations at the dictionary interface level for the flat file store.

Author: Eric Huang

These functions are not intended to be used directly. The entry point here is the initialization function, which is used to bind these functions to a dictionary.

Copyright: Copyright 2017 The University of British Columbia, IonDB Project Contributors (see AUTHORS.md)

Redistribution and use in source and binary forms, with or without: modification, are permitted provided that the following conditions are met:

1.Redistributions of source code must retain the above copyright notice,: this list of conditions and the following disclaimer.

2.Redistributions in binary form must reproduce the above copyright notice,: this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3.Neither the name of the copyright holder nor the names of its contributors: may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS": AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Definition in file flat_file_dictionary_handler.h.

Include dependency graph for flat_file_dictionary_handler.h:

This graph shows which files directly or indirectly include this file:

Functions
void	ffdict_init (ion_dictionary_handler_t *handler)
	Given the `handler` instance, bind the appropriate flat file functions. More...

ion_status_t	ffdict_insert (ion_dictionary_t *dictionary, ion_key_t key, ion_value_t value)
	Given a record ( `key`, `value` ), insert it into the dictionary. More...

ion_status_t	ffdict_get (ion_dictionary_t *dictionary, ion_key_t key, ion_value_t value)
	Performs a "get" operation on the dictionary to retrieve a single record. More...

ion_err_t	ffdict_create_dictionary (ion_dictionary_id_t id, ion_key_type_t key_type, ion_key_size_t key_size, ion_value_size_t value_size, ion_dictionary_size_t dictionary_size, ion_dictionary_compare_t compare, ion_dictionary_handler_t handler, ion_dictionary_t dictionary)
	Creates an instance of a flat file backed dictionary. More...

ion_status_t	ffdict_delete (ion_dictionary_t *dictionary, ion_key_t key)
	Removes all instances of any record with key equal to `key`. More...

ion_err_t	ffdict_delete_dictionary (ion_dictionary_t *dictionary)
	Cleans up all files created by the dictionary, and frees any allocated memory. More...

ion_err_t	ffdict_destroy_dictionary (ion_dictionary_id_t id)
	Cleans up all files created by the dictionary, and frees any allocated memory, for an already closed dictionary. More...

ion_status_t	ffdict_update (ion_dictionary_t *dictionary, ion_key_t key, ion_value_t value)
	Updates all records stored at `key` to have value equal to `value`. More...

Function Documentation

ion_err_t ffdict_create_dictionary	(	ion_dictionary_id_t	id,
		ion_key_type_t	key_type,
		ion_key_size_t	key_size,
		ion_value_size_t	value_size,
		ion_dictionary_size_t	dictionary_size,
		ion_dictionary_compare_t	compare,
		ion_dictionary_handler_t *	handler,
		ion_dictionary_t *	dictionary
	)

Creates an instance of a flat file backed dictionary.

Parameters

[in]	id	The ID to assign to the dictionary. This is either user defined or is given by the master table.
[in]	key_type	The category of key used by the dictionary. See ION_KEY_TYPE for more information.
[in]	key_size	The size of the keys used for this dictionary, specified in bytes. It is strongly recommended to use a `sizeof()` directive to specify this size to avoid painful problems.
[in]	value_size	Same as above, for values.
[in]	dictionary_size	Designates how many records we buffer in memory. Higher means better overall performance at the cost of increased memory usage.
[in]	compare	The function pointer that designates how to compare two keys. This is given by the upper dictionary layers.
[in]	handler	The allocated, initialized handler that will be bound to the dictionary instance.
[in]	dictionary	The allocated dictionary instance that we are going to initialize.

Returns: The resulting status of the operation.

Definition at line 398 of file flat_file_dictionary_handler.c.

   {
     dictionary->instance = malloc(sizeof(ion_flat_file_t));
 
     if (NULL == dictionary->instance) {
         return err_out_of_memory;
     }
 
     dictionary->instance->compare   = compare;
     dictionary->instance->type      = dictionary_type_flat_file_t;
 
     ion_err_t result = flat_file_initialize((ion_flat_file_t *) dictionary->instance, id, key_type, key_size, value_size, dictionary_size);
 
     if ((err_ok == result) && (NULL != handler)) {
         dictionary->handler = handler;
     }
 
     return result;
 }

Here is the call graph for this function:

Here is the caller graph for this function:

ion_status_t ffdict_delete	(	ion_dictionary_t *	dictionary,
		ion_key_t	key
	)

Removes all instances of any record with key equal to key.

Parameters

[in]	dictionary	Which dictionary to delete from.
[in]	key	Designated key to look for and remove.

Returns: The resulting status of the operation.

Definition at line 427 of file flat_file_dictionary_handler.c.

   {
     return flat_file_delete((ion_flat_file_t *) dictionary->instance, key);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

ion_err_t ffdict_delete_dictionary ( ion_dictionary_t * dictionary )

Cleans up all files created by the dictionary, and frees any allocated memory.

Parameters

[in] dictionary Which dictionary instance to delete.

Returns: The resulting status of the operation.

Definition at line 435 of file flat_file_dictionary_handler.c.

   {
     ion_err_t result = flat_file_destroy((ion_flat_file_t *) dictionary->instance);
 
     free(dictionary->instance);
     dictionary->instance = NULL;
     return result;
 }

Here is the call graph for this function:

Here is the caller graph for this function:

ion_err_t ffdict_destroy_dictionary ( ion_dictionary_id_t id )

Cleans up all files created by the dictionary, and frees any allocated memory, for an already closed dictionary.

Parameters

[in] id The identifier identifying the dictionary to delete.

Returns: The resulting status of the operation.

Definition at line 446 of file flat_file_dictionary_handler.c.

   {
     char filename[ION_MAX_FILENAME_LENGTH];
 
     dictionary_get_filename(id, "ffs", filename);
 
     if (0 != fremove(filename)) {
         return err_file_delete_error;
     }
 
     return err_ok;
 }

Here is the call graph for this function:

Here is the caller graph for this function:

ion_status_t ffdict_get	(	ion_dictionary_t *	dictionary,
		ion_key_t	key,
		ion_value_t	value
	)

Performs a "get" operation on the dictionary to retrieve a single record.

Given a key, returns the associated value stored under that key. If there are duplicate records all with the same key, the exact one that is returned is undefined. If you need to get all records stored under a specific key, use a cursor query.

Parameters

[in]	dictionary	Which dictionary to perform the operation on.
[in]	key	The desired search key.
[out]	value	The output location in which to write the returned value. This space must be allocated by the user to at least `value_size` bytes, as originally defined on dictionary creation.

Returns: The resulting status of the operation.

Definition at line 389 of file flat_file_dictionary_handler.c.

   {
     return flat_file_get((ion_flat_file_t *) dictionary->instance, key, value);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void ffdict_init ( ion_dictionary_handler_t * handler )

Given the handler instance, bind the appropriate flat file functions.

Parameters

[in] handler The handler is assumed to be memory that is allocated and initialized by the user.

Definition at line 364 of file flat_file_dictionary_handler.c.

   {
     handler->insert             = ffdict_insert;
     handler->create_dictionary  = ffdict_create_dictionary;
     handler->get                = ffdict_get;
     handler->update             = ffdict_update;
     handler->find               = ffdict_find;
     handler->remove             = ffdict_delete;
     handler->delete_dictionary  = ffdict_delete_dictionary;
     handler->destroy_dictionary = ffdict_destroy_dictionary;
     handler->open_dictionary    = ffdict_open_dictionary;
     handler->close_dictionary   = ffdict_close_dictionary;
 }

Here is the call graph for this function:

Here is the caller graph for this function:

ion_status_t ffdict_insert	(	ion_dictionary_t *	dictionary,
		ion_key_t	key,
		ion_value_t	value
	)

Given a record ( key, value ), insert it into the dictionary.

Parameters

[in]	dictionary	The initialized dictionary instance we want to insert into.
[in]	key	The key portion of the record to be inserted.
[in]	value	The value portion of the record to be inserted.

Returns: The resulting status of the operation.

Definition at line 380 of file flat_file_dictionary_handler.c.

   {
     return flat_file_insert((ion_flat_file_t *) dictionary->instance, key, value);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

ion_status_t ffdict_update	(	ion_dictionary_t *	dictionary,
		ion_key_t	key,
		ion_value_t	value
	)

Updates all records stored at key to have value equal to value.

If no records are stored at key, then an "upsert" (insert instead of update) is performed.

Parameters

[in]	dictionary	Which dictionary to update.
[in]	key	Target key to update.
[in]	value	New value to update to.

Returns: The resulting status of the operation.

Definition at line 461 of file flat_file_dictionary_handler.c.

   {
     return flat_file_update((ion_flat_file_t *) dictionary->instance, key, value);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

Description

Functions

Function Documentation