#include "flat_file_types.h"
Description
Implementation specific declarations for the flat file store.
- 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.h.
Functions | |
ion_err_t | flat_file_initialize (ion_flat_file_t *flat_file, 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) |
Initializes the flat file implementation and creates all necessary files. More... | |
ion_err_t | flat_file_destroy (ion_flat_file_t *flat_file) |
Destroys and cleans up any implementation specific memory or files. More... | |
ion_status_t | flat_file_insert (ion_flat_file_t *flat_file, ion_key_t key, ion_value_t value) |
Inserts the given record into the flat file store. More... | |
ion_status_t | flat_file_get (ion_flat_file_t *flat_file, ion_key_t key, ion_value_t value) |
Fetches the record stored with the given key . More... | |
ion_status_t | flat_file_delete (ion_flat_file_t *flat_file, ion_key_t key) |
Deletes all records stored with the given key . More... | |
ion_status_t | flat_file_update (ion_flat_file_t *flat_file, ion_key_t key, ion_value_t value) |
Updates all records stored with the given key to have value . More... | |
ion_err_t | flat_file_close (ion_flat_file_t *flat_file) |
Closes and frees any memory associated with the flat file. More... | |
ion_err_t | flat_file_scan (ion_flat_file_t *flat_file, ion_fpos_t start_location, ion_fpos_t *location, ion_flat_file_row_t *row, ion_byte_t scan_direction, ion_flat_file_predicate_t predicate,...) |
Performs a linear scan of the flat file writing the first location seen that satisfies the given predicate to location . More... | |
ion_boolean_t | flat_file_predicate_key_match (ion_flat_file_t *flat_file, ion_flat_file_row_t *row, va_list *args) |
Predicate function to return any row that has an exact match to the given target key. More... | |
ion_boolean_t | flat_file_predicate_within_bounds (ion_flat_file_t *flat_file, ion_flat_file_row_t *row, va_list *args) |
Predicate function to return any row that has a key such that lower_bound <= key <= upper_bound holds true. More... | |
ion_boolean_t | flat_file_predicate_not_empty (ion_flat_file_t *flat_file, ion_flat_file_row_t *row, va_list *args) |
Predicate function to return any row that is not empty or deleted. More... | |
ion_err_t | flat_file_read_row (ion_flat_file_t *flat_file, ion_fpos_t location, ion_flat_file_row_t *row) |
Reads the row specified by the given location into the buffer. More... | |
ion_err_t | flat_file_binary_search (ion_flat_file_t *flat_file, ion_key_t target_key, ion_fpos_t *location) |
Performs a binary search for the given target_key , returning to location the first-less-than-or-equal key within the flat file. This can only be used if sorted_mode is enabled within the flat file. More... | |
Function Documentation
ion_err_t flat_file_binary_search | ( | ion_flat_file_t * | flat_file, |
ion_key_t | target_key, | ||
ion_fpos_t * | location | ||
) |
Performs a binary search for the given target_key
, returning to location
the first-less-than-or-equal key within the flat file. This can only be used if sorted_mode
is enabled within the flat file.
In the case of duplicates, this function will scroll to the beginning of the block of duplicates, before writing back to location
. As a result, it is guaranteed that the returned index points to the first key in a contiguous block of duplicate keys. If no key in the flat file satisfies the condition of being less-than-or-equal, then -1
is written back to location
. This function will only return records that are not deleted.
- Parameters
-
[in] flat_file Which flat file instance to search within. [in] target_key Desired key to search for. [out] location Found location to write back into. Must be allocated by caller.
- Returns
- Resulting status of the binary search operation.
Definition at line 638 of file flat_file.c.
ion_err_t flat_file_close | ( | ion_flat_file_t * | flat_file | ) |
Closes and frees any memory associated with the flat file.
- Parameters
-
flat_file Which flat file to close.
- Returns
- Status of closure.
Definition at line 624 of file flat_file.c.
ion_status_t flat_file_delete | ( | ion_flat_file_t * | flat_file, |
ion_key_t | key | ||
) |
Deletes all records stored with the given key
.
- Parameters
-
[in] flat_file Which flat file to delete in. [in] key Specified key to find and delete.
- Returns
- Resulting status of the operation.
- See also
- ffdict_delete
Definition at line 495 of file flat_file.c.
ion_err_t flat_file_destroy | ( | ion_flat_file_t * | flat_file | ) |
Destroys and cleans up any implementation specific memory or files.
- Parameters
-
[in] flat_file Given flat file instance to destroy.
- Returns
- The resulting status of destruction.
- See also
- ffdict_delete_dictionary
Definition at line 134 of file flat_file.c.
ion_status_t flat_file_get | ( | ion_flat_file_t * | flat_file, |
ion_key_t | key, | ||
ion_value_t | value | ||
) |
Fetches the record stored with the given key
.
- Parameters
-
[in] flat_file Which flat file to look in. [in] key Specified key to look for. [out] value Value portion of the record to insert.
- Returns
- Resulting status of the operation.
- See also
- ffdict_get
Definition at line 439 of file flat_file.c.
ion_err_t flat_file_initialize | ( | ion_flat_file_t * | flat_file, |
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 | ||
) |
Initializes the flat file implementation and creates all necessary files.
A check is done to see if this is actually an attempt to open a previously existing flat file instance. This (should) only happen when this is called from an open context instead of an initialize. The flat file supports a special mode called "sorted mode". This is an append only mode that assumes all keys come in monotonic non-decreasing order. In this mode, search operations are significantly faster, but the store does not support deletions while in sorted mode.
- Parameters
-
[in] flat_file Given instance of a flat file struct to initialize. This must be allocated heap memory, as destruction will assume that it needs to be freed. [in] id The assigned ID of this dictionary instance. [in] key_type Key category to use for this instance. [in] key_size Key size, in bytes used for this instance. [in] value_size Value size, in bytes used for this instance. [in] dictionary_size Dictionary size is interpreted as how many records (key value pairs) are buffered. This should be given as somewhere between 1 (minimum) and the page size of the device you are working on.
- Returns
- The status of initialization.
- See also
- ffdict_create_dictionary
Definition at line 40 of file flat_file.c.
ion_status_t flat_file_insert | ( | ion_flat_file_t * | flat_file, |
ion_key_t | key, | ||
ion_value_t | value | ||
) |
Inserts the given record into the flat file store.
- Parameters
-
[in] flat_file Which flat file to insert into. [in] key Key portion of the record to insert. [in] value Value portion of the record to insert.
- Returns
- Resulting status of insertion.
- See also
- ffdict_insert
Definition at line 388 of file flat_file.c.
ion_boolean_t flat_file_predicate_key_match | ( | ion_flat_file_t * | flat_file, |
ion_flat_file_row_t * | row, | ||
va_list * | args | ||
) |
Predicate function to return any row that has an exact match to the given target key.
We expect one ion_key_t to be in args
.
- See also
- ion_flat_file_predicate_t
Definition at line 280 of file flat_file.c.
ion_boolean_t flat_file_predicate_not_empty | ( | ion_flat_file_t * | flat_file, |
ion_flat_file_row_t * | row, | ||
va_list * | args | ||
) |
Predicate function to return any row that is not empty or deleted.
- See also
- ion_flat_file_predicate_t
Definition at line 268 of file flat_file.c.
ion_boolean_t flat_file_predicate_within_bounds | ( | ion_flat_file_t * | flat_file, |
ion_flat_file_row_t * | row, | ||
va_list * | args | ||
) |
Predicate function to return any row that has a key such that lower_bound <= key <= upper_bound
holds true.
We expect two ion_key_t parameters to be in args
- the first to represent the lower bound of the key, and the second to represent the upper bound.
- See also
- ion_flat_file_predicate_t
Definition at line 291 of file flat_file.c.
ion_err_t flat_file_read_row | ( | ion_flat_file_t * | flat_file, |
ion_fpos_t | location, | ||
ion_flat_file_row_t * | row | ||
) |
Reads the row specified by the given location into the buffer.
The returned row is given by attaching pointers correctly from the given row parameter. These pointers are associated with the internal read buffer of the flat file. You should assume that the row does not have a lifetime beyond the scope of where you call this function - any subsequent operation that mutates the read buffer will cause the row to become garbage. Copy the row data out if you want it to persist. If the requested row has already been loaded by a prior call to flat_file_scan, then it will retrieve it as a cache hit directly from the buffer. Otherwise, it will do a seek and read to fetch the row.
- Parameters
-
[in] flat_file Which flat file instance to read from. [in] location Which row index to read. This function will compute the file offset of the row index. [in] row Write back row to place read data from the desired location
.
- Returns
- Resulting status of the several file operations used to perform the read.
Definition at line 350 of file flat_file.c.
ion_err_t flat_file_scan | ( | ion_flat_file_t * | flat_file, |
ion_fpos_t | start_location, | ||
ion_fpos_t * | location, | ||
ion_flat_file_row_t * | row, | ||
ion_byte_t | scan_direction, | ||
ion_flat_file_predicate_t | predicate, | ||
... | |||
) |
Performs a linear scan of the flat file writing the first location seen that satisfies the given predicate
to location
.
If the scan falls through, then the location is written as the EOF position of the file. The variadic arguments accepted by this function are passed into the predicate's additional parameters. This can be used to provide additional context to the predicate for use in determining whether or not the row is a match.
- Parameters
-
[in] flat_file Which flat file instance to scan. [in] start_location Where to begin the scan. This is given as a row index. If given as -1, then it is assumed to be either the start of file or end of file, depending on the state of scan_direction
.[out] location Allocated memory location to write back the found location into. Is not changed in the event of a failure or error condition. This location is given back as a row index. [out] row A row struct to write back the found row into. This is allocated by the user. [in] scan_direction Scans in the direction provided. [in] predicate Given test function to check each row against. Once this function returns true, the scan is terminated and the found location and row are written back to their respective output parameters.
- Returns
- Resulting status of scan.
Definition at line 157 of file flat_file.c.
ion_status_t flat_file_update | ( | ion_flat_file_t * | flat_file, |
ion_key_t | key, | ||
ion_value_t | value | ||
) |
Updates all records stored with the given key
to have value
.
- Parameters
-
[in] flat_file Which flat file to update in. [in] key Specified key to find and update. [in] value New value to replace old values with.
- Returns
- Resulting status of the operation.
- See also
- ffdict_update
Definition at line 560 of file flat_file.c.