linked_file_bag.h File Reference

#include "../key_value/kv_system.h"
#include "ion_file.h"

Description

API for a persistent bag. Items are linked together in a singly linked list.

Author

Graeme Douglas

The bag is constituted of several sub bags, described by the singly linked lists. All operations act on these sub bags.

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.h.

Include dependency graph for linked_file_bag.h:

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

Classes
struct	linkedfilebag
	A handler struct for a linked file bag instance. More...

Macros
#define	ION_LFB_NULL   ION_FILE_NULL

Typedefs
typedef struct linkedfilebag	ion_lfb_t
	A handler struct for a linked file bag instance. More...

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_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_LFB_NULL   ION_FILE_NULL

Definition at line 50 of file linked_file_bag.h.

Typedef Documentation

typedef struct linkedfilebag ion_lfb_t

A handler struct for a linked file bag instance.

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.

  {
    return lfb_update_next(bag, offset, bag->next_empty);
}

Here is the call graph for this function:

Here is the caller graph for this function:

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           error;
    ion_file_offset_t   next;

    while (ION_LFB_NULL != offset) {
        error = ion_fread_at(bag->file_handle, offset, sizeof(ion_file_offset_t), (ion_byte_t *) &next);

        if (err_ok != error) {
            return error;
        }

        error = lfb_delete(bag, offset);

        if (err_ok != error) {
            return error;
        }

        if (NULL != count) {
            (*count)++;
        }

        offset = next;
    }

    return err_ok;
}

Here is the call graph for this function:

Here is the caller graph for this function:

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 error;

    error = ion_fread_at(bag->file_handle, offset, sizeof(ion_file_offset_t), (ion_byte_t *) next);

    if (err_ok != error) {
        return error;
    }

    error = ion_fread_at(bag->file_handle, offset + sizeof(ion_file_offset_t), num_bytes, write_to);

    return error;
}

Here is the call graph for this function:

Here is the caller graph for this function:

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_file_offset_t   next_empty;
    ion_err_t           error;

    next_empty = ION_LFB_NULL;

    if (ION_LFB_NULL != bag->next_empty) {
        error = ion_fread_at(bag->file_handle, bag->next_empty, sizeof(ion_file_offset_t), (ion_byte_t *) &next_empty);

        if (err_ok != error) {
            return error;
        }

        *wrote_at = bag->next_empty;
    }
    else {
        *wrote_at = ion_fend(bag->file_handle);
    }

    error = ion_fwrite_at(bag->file_handle, *wrote_at, sizeof(ion_file_offset_t), (ion_byte_t *) &next);

    if (err_ok != error) {
        return error;
    }

    error = ion_fwrite_at(bag->file_handle, *wrote_at + sizeof(ion_file_offset_t), num_bytes, to_write);

    if (err_ok != error) {
        return error;
    }

    bag->next_empty = next_empty;

    return err_ok;
}

Here is the call graph for this function:

Here is the caller graph for this function:

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 error;

    if (NULL != next) {
        error = lfb_update_next(bag, offset, *next);

        if (err_ok != error) {
            return error;
        }
    }

    error = ion_fwrite_at(bag->file_handle, offset + sizeof(ion_file_offset_t), num_bytes, to_write);

    return error;
}

Here is the call graph for this function:

Here is the caller graph for this function:

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           error;
    ion_file_offset_t   next;

    while (ION_LFB_NULL != offset) {
        error = ion_fread_at(bag->file_handle, offset, sizeof(ion_file_offset_t), (ion_byte_t *) &next);

        if (err_ok != error) {
            return error;
        }

        error = lfb_update(bag, offset, num_bytes, to_write, NULL);

        if (err_ok != error) {
            return error;
        }

        if (NULL != count) {
            (*count)++;
        }

        offset = next;
    }

    return err_ok;
}

Here is the call graph for this function:

Here is the caller graph for this function: