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.

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
bagA pointer to the initialized linked file bag handler for which we wish to delete the record from.
offsetThe 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.

141  {
142  return lfb_update_next(bag, offset, bag->next_empty);
143 }
ion_file_offset_t next_empty
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.

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
bagA pointer to the initialized linked file bag handler for which we wish to delete from.
offsetThe offset of the first linked record to delete from.
countA 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.

150  {
153 
154  while (ION_LFB_NULL != offset) {
155  error = ion_fread_at(bag->file_handle, offset, sizeof(ion_file_offset_t), (ion_byte_t *) &next);
156 
157  if (err_ok != error) {
158  return error;
159  }
160 
161  error = lfb_delete(bag, offset);
162 
163  if (err_ok != error) {
164  return error;
165  }
166 
167  if (NULL != count) {
168  (*count)++;
169  }
170 
171  offset = next;
172  }
173 
174  return err_ok;
175 }
unsigned char ion_byte_t
A byte type.
Definition: kv_system.h:232
ion_err_t lfb_delete(ion_lfb_t *bag, ion_file_offset_t offset)
Attempt to delete a record stored at a given offset.
#define ION_LFB_NULL
#define next(b)
Definition: bpp_tree.c:82
ion_file_handle_t file_handle
char ion_err_t
The error type used to store error codes.
Definition: kv_system.h:226
long ion_file_offset_t
Definition: ion_file.h:47
#define error(rc)
Definition: bpp_tree.c:139
ion_err_t ion_fread_at(ion_file_handle_t file, ion_file_offset_t offset, unsigned int num_bytes, ion_byte_t *write_to)
Definition: ion_file.c:237

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
bagA pointer to the linked file bag handler object which we wish to add this item to.
offsetWhere to read the information from within the file bag.
num_bytesThe number of bytes to read into write_to.
write_toA pointer for a memory buffer to write the retrieved data into.
nextA 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.

94  {
96 
97  error = ion_fread_at(bag->file_handle, offset, sizeof(ion_file_offset_t), (ion_byte_t *) next);
98 
99  if (err_ok != error) {
100  return error;
101  }
102 
103  error = ion_fread_at(bag->file_handle, offset + sizeof(ion_file_offset_t), num_bytes, write_to);
104 
105  return error;
106 }
unsigned char ion_byte_t
A byte type.
Definition: kv_system.h:232
#define next(b)
Definition: bpp_tree.c:82
ion_file_handle_t file_handle
char ion_err_t
The error type used to store error codes.
Definition: kv_system.h:226
long ion_file_offset_t
Definition: ion_file.h:47
#define error(rc)
Definition: bpp_tree.c:139
ion_err_t ion_fread_at(ion_file_handle_t file, ion_file_offset_t offset, unsigned int num_bytes, ion_byte_t *write_to)
Definition: ion_file.c:237

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
bagA pointer to the linked file bag handler object which we wish to add this item to.
to_writeA pointer to the buffer of data to write.
num_bytesThe number of bytes to write from the start of to_write.
nextThe offset of next item in this bag, if one exists (otherwise, pass in -1).
wrote_atA 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.

51  {
52  ion_file_offset_t next_empty;
54 
55  next_empty = ION_LFB_NULL;
56 
57  if (ION_LFB_NULL != bag->next_empty) {
58  error = ion_fread_at(bag->file_handle, bag->next_empty, sizeof(ion_file_offset_t), (ion_byte_t *) &next_empty);
59 
60  if (err_ok != error) {
61  return error;
62  }
63 
64  *wrote_at = bag->next_empty;
65  }
66  else {
67  *wrote_at = ion_fend(bag->file_handle);
68  }
69 
70  error = ion_fwrite_at(bag->file_handle, *wrote_at, sizeof(ion_file_offset_t), (ion_byte_t *) &next);
71 
72  if (err_ok != error) {
73  return error;
74  }
75 
76  error = ion_fwrite_at(bag->file_handle, *wrote_at + sizeof(ion_file_offset_t), num_bytes, to_write);
77 
78  if (err_ok != error) {
79  return error;
80  }
81 
82  bag->next_empty = next_empty;
83 
84  return err_ok;
85 }
unsigned char ion_byte_t
A byte type.
Definition: kv_system.h:232
#define ION_LFB_NULL
#define next(b)
Definition: bpp_tree.c:82
ion_file_handle_t file_handle
char ion_err_t
The error type used to store error codes.
Definition: kv_system.h:226
long ion_file_offset_t
Definition: ion_file.h:47
ion_file_offset_t next_empty
#define error(rc)
Definition: bpp_tree.c:139
ion_err_t ion_fwrite_at(ion_file_handle_t file, ion_file_offset_t offset, unsigned int num_bytes, ion_byte_t *to_write)
Definition: ion_file.c:177
ion_file_offset_t ion_fend(ion_file_handle_t file)
Definition: ion_file.c:143
ion_err_t ion_fread_at(ion_file_handle_t file, ion_file_offset_t offset, unsigned int num_bytes, ion_byte_t *write_to)
Definition: ion_file.c:237

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
bagA pointer to the linked file bag handler for which we wish to update a record.
offsetThe offset where the record data starts.
num_bytesThe number of bytes to write to the record.
to_writeThe data to actually write.
nextA 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.

184  {
186 
187  if (NULL != next) {
188  error = lfb_update_next(bag, offset, *next);
189 
190  if (err_ok != error) {
191  return error;
192  }
193  }
194 
195  error = ion_fwrite_at(bag->file_handle, offset + sizeof(ion_file_offset_t), num_bytes, to_write);
196 
197  return error;
198 }
#define next(b)
Definition: bpp_tree.c:82
ion_file_handle_t file_handle
char ion_err_t
The error type used to store error codes.
Definition: kv_system.h:226
long ion_file_offset_t
Definition: ion_file.h:47
#define error(rc)
Definition: bpp_tree.c:139
ion_err_t ion_fwrite_at(ion_file_handle_t file, ion_file_offset_t offset, unsigned int num_bytes, ion_byte_t *to_write)
Definition: ion_file.c:177
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.

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
bagA pointer to the linked file bag handler for which we wish to update a record.
offsetThe offset of the first record to update.
num_bytesThe number of bytes to write to each record.
to_writeThe data to actually write to each record.
countA 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.

207  {
210 
211  while (ION_LFB_NULL != offset) {
212  error = ion_fread_at(bag->file_handle, offset, sizeof(ion_file_offset_t), (ion_byte_t *) &next);
213 
214  if (err_ok != error) {
215  return error;
216  }
217 
218  error = lfb_update(bag, offset, num_bytes, to_write, NULL);
219 
220  if (err_ok != error) {
221  return error;
222  }
223 
224  if (NULL != count) {
225  (*count)++;
226  }
227 
228  offset = next;
229  }
230 
231  return err_ok;
232 }
unsigned char ion_byte_t
A byte type.
Definition: kv_system.h:232
#define ION_LFB_NULL
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.
#define next(b)
Definition: bpp_tree.c:82
ion_file_handle_t file_handle
char ion_err_t
The error type used to store error codes.
Definition: kv_system.h:226
long ion_file_offset_t
Definition: ion_file.h:47
#define error(rc)
Definition: bpp_tree.c:139
ion_err_t ion_fread_at(ion_file_handle_t file, ion_file_offset_t offset, unsigned int num_bytes, ion_byte_t *write_to)
Definition: ion_file.c:237

Here is the call graph for this function:

Here is the caller graph for this function: