#include "linked_file_bag.h"
Description
API for a persistent bag. Items are linked together in a singly linked list.
- 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 linked_file_bag.c.
Macros | |
#define | ION_NULL ((void *) 0) |
Functions | |
ion_err_t | lfb_put (ion_lfb_t *bag, ion_byte_t *to_write, unsigned int num_bytes, ion_file_offset_t next, ion_file_offset_t *wrote_at) |
Add an item to the linked file bag. More... | |
ion_err_t | lfb_get (ion_lfb_t *bag, ion_file_offset_t offset, unsigned int num_bytes, ion_byte_t *write_to, ion_file_offset_t *next) |
Add an item to the linked file bag. More... | |
ion_err_t | lfb_update_next (ion_lfb_t *bag, ion_file_offset_t offset, ion_file_offset_t next) |
Update the next offset for the record stored at offset . More... | |
ion_err_t | lfb_delete (ion_lfb_t *bag, ion_file_offset_t offset) |
Attempt to delete a record stored at a given offset. More... | |
ion_err_t | lfb_delete_all (ion_lfb_t *bag, ion_file_offset_t offset, ion_result_count_t *count) |
Attempt to delete all contents from the bag starting at a given offset. More... | |
ion_err_t | lfb_update (ion_lfb_t *bag, ion_file_offset_t offset, unsigned int num_bytes, ion_byte_t *to_write, ion_file_offset_t *next) |
Attempt to update a record within a linked file bag at a given offset. More... | |
ion_err_t | lfb_update_all (ion_lfb_t *bag, ion_file_offset_t offset, unsigned int num_bytes, ion_byte_t *to_write, ion_result_count_t *count) |
Attempt to update all records kept within a specific bag, starting at some record at a given offset. More... | |
Macro Definition Documentation
#define ION_NULL ((void *) 0) |
Definition at line 41 of file linked_file_bag.c.
Function Documentation
ion_err_t lfb_delete | ( | ion_lfb_t * | bag, |
ion_file_offset_t | offset | ||
) |
Attempt to delete a record stored at a given offset.
- Parameters
-
bag A pointer to the initialized linked file bag handler for which we wish to delete the record from. offset The offset of the record to remove from its bag.
- Returns
- An error code describing the result of the call.
Definition at line 138 of file linked_file_bag.c.
ion_err_t lfb_delete_all | ( | ion_lfb_t * | bag, |
ion_file_offset_t | offset, | ||
ion_result_count_t * | count | ||
) |
Attempt to delete all contents from the bag starting at a given offset.
This will not delete everything stored in the object with handle bag
, but instead delete everything linked starting with the record at offset
.
- Parameters
-
bag A pointer to the initialized linked file bag handler for which we wish to delete from. offset The offset of the first linked record to delete from. count A pointer to write count data to. If it is NULL
, then no data will be written.
- Returns
- An error code describing the result of the call.
Definition at line 146 of file linked_file_bag.c.
ion_err_t lfb_get | ( | ion_lfb_t * | bag, |
ion_file_offset_t | offset, | ||
unsigned int | num_bytes, | ||
ion_byte_t * | write_to, | ||
ion_file_offset_t * | next | ||
) |
Add an item to the linked file bag.
- Parameters
-
bag A pointer to the linked file bag handler object which we wish to add this item to. offset Where to read the information from within the file bag. num_bytes The number of bytes to read into write_to
.write_to A pointer for a memory buffer to write the retrieved data into. next A pointer to a file offset (already allocated) which is written to describing where the next item in this bag is located, for traversal purposes. This read from the file does NOT count towards the num_bytes
parameter specified.
- Returns
- An error code describing the result of the call.
Definition at line 88 of file linked_file_bag.c.
ion_err_t lfb_put | ( | ion_lfb_t * | bag, |
ion_byte_t * | to_write, | ||
unsigned int | num_bytes, | ||
ion_file_offset_t | next, | ||
ion_file_offset_t * | wrote_at | ||
) |
Add an item to the linked file bag.
- Parameters
-
bag A pointer to the linked file bag handler object which we wish to add this item to. to_write A pointer to the buffer of data to write. num_bytes The number of bytes to write from the start of to_write
.next The offset of next item in this bag, if one exists (otherwise, pass in -1
).wrote_at A pointer to an already allocated file offset used to write where the linked file bag actually wrote. This is useful if the calling function needs to use this information.
- Returns
- An error code describing the result of the call.
Definition at line 45 of file linked_file_bag.c.
ion_err_t lfb_update | ( | ion_lfb_t * | bag, |
ion_file_offset_t | offset, | ||
unsigned int | num_bytes, | ||
ion_byte_t * | to_write, | ||
ion_file_offset_t * | next | ||
) |
Attempt to update a record within a linked file bag at a given offset.
This will update a record in place. If num_bytes
does not match the size of the record already stored (especially if num_bytes
is larger than the size of the record already stored) then bad things may ensue.
- Parameters
-
bag A pointer to the linked file bag handler for which we wish to update a record. offset The offset where the record data starts. num_bytes The number of bytes to write to the record. to_write The data to actually write. next A pointer to a file offset (already allocated), which will have the file offset of the next record in this bag written into it. This can be useful for traversal purposes.
- Returns
- An error code describing the result of the call.
Definition at line 178 of file linked_file_bag.c.
ion_err_t lfb_update_all | ( | ion_lfb_t * | bag, |
ion_file_offset_t | offset, | ||
unsigned int | num_bytes, | ||
ion_byte_t * | to_write, | ||
ion_result_count_t * | count | ||
) |
Attempt to update all records kept within a specific bag, starting at some record at a given offset.
All records linked should be the same size (num_bytes
) or else wastage or corruption may occur.
- Parameters
-
bag A pointer to the linked file bag handler for which we wish to update a record. offset The offset of the first record to update. num_bytes The number of bytes to write to each record. to_write The data to actually write to each record. count A pointer to write count data to. If it is NULL
, then no data will be written.
- Returns
- An error code describing the result of the call.
Definition at line 201 of file linked_file_bag.c.
ion_err_t lfb_update_next | ( | ion_lfb_t * | bag, |
ion_file_offset_t | offset, | ||
ion_file_offset_t | next | ||
) |
Update the next offset for the record stored at offset
.
- Parameters
-
bag A pointer to the initialized handler for the linked file bag we wish to update. offset The offset of the record to set the next offset of. next The offset of the record to be referenced in the record stored starting at offset
.
- Returns
- An error code describing the result of the call.
Definition at line 121 of file linked_file_bag.c.