The Sequence Toolkit
www.sequence-toolkit.com
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros
Functions
stk_sequence_api.h File Reference
#include "stk_sequence.h"
#include "stk_service.h"
#include "stk_env.h"
Include dependency graph for stk_sequence_api.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

stk_sequence_tstk_create_sequence (stk_env_t *env, char *name, stk_sequence_id id, stk_sequence_type type, stk_service_type svctype, stk_options_t *options)
 
stk_ret stk_destroy_sequence (stk_sequence_t *seq)
 
void stk_hold_sequence (stk_sequence_t *seq)
 
stk_sequence_id stk_acquire_sequence_id (stk_env_t *env, stk_service_type type)
 
stk_ret stk_release_sequence_id (stk_env_t *env, stk_sequence_id)
 
stk_ret stk_add_reference_to_sequence (stk_sequence_t *seq, void *data_ptr, stk_uint64 sz, stk_uint64 user_type)
 
stk_ret stk_add_sequence_reference_in_sequence (stk_sequence_t *seq, stk_sequence_t *merge_seq, stk_uint64 user_type)
 
stk_ret stk_update_ref_data_in_sequence (stk_sequence_t *seq, stk_generation_id *gen_id)
 
stk_ret stk_copy_to_sequence (stk_sequence_t *seq, void *data_ptr, stk_uint64 sz, stk_uint64 user_type)
 
stk_ret stk_copy_to_sequence_meta_data (stk_sequence_t *seq, void *data_ptr, stk_uint64 sz, stk_uint64 user_type)
 
stk_uint64 stk_remove_sequence_data_by_type (stk_sequence_t *seq, stk_uint64 user_type, stk_uint64 max_instances)
 
stk_sequence_id stk_get_sequence_id (stk_sequence_t *seq)
 
stk_ret stk_set_sequence_id (stk_sequence_t *seq, stk_sequence_id id)
 
stk_sequence_type stk_get_sequence_type (stk_sequence_t *seq)
 
stk_ret stk_set_sequence_type (stk_sequence_t *seq, stk_sequence_type type)
 
stk_ret stk_set_sequence_name (stk_sequence_t *seq, char *name)
 
char * stk_get_sequence_name (stk_sequence_t *seq)
 
stk_generation_id stk_bump_sequence_generation (stk_sequence_t *seq)
 
stk_generation_id stk_get_sequence_generation (stk_sequence_t *seq)
 
stk_env_tstk_env_from_sequence (stk_sequence_t *seq)
 
int stk_number_of_sequence_elements (stk_sequence_t *seq)
 
int stk_has_any_sequence_elements (stk_sequence_t *seq)
 
stk_ret stk_alloc_in_sequence (stk_sequence_t *seq, stk_uint64 sz, stk_uint64 user_type)
 
void * stk_last_sequence_element (stk_sequence_t *seq)
 
stk_ret stk_iterate_sequence (stk_sequence_t *seq, stk_sequence_cb element_cb, void *clientd)
 
stk_ret stk_iterate_complete_sequence (stk_sequence_t *seq, stk_sequence_cb before_cb, stk_sequence_cb element_cb, stk_sequence_cb after_cb, void *clientd)
 
stk_sequence_iterator_tstk_sequence_iterator (stk_sequence_t *seq)
 
stk_ret stk_end_sequence_iterator (stk_sequence_iterator_t *seqiter)
 
void * stk_sequence_iterator_realloc_segment (stk_sequence_iterator_t *seqiter, stk_uint64 sz)
 
void * stk_sequence_iterator_ensure_segment_size (stk_sequence_iterator_t *seqiter, stk_uint64 sz)
 
void * stk_sequence_iterator_data (stk_sequence_iterator_t *seqiter)
 
void * stk_sequence_iterator_next (stk_sequence_iterator_t *seqiter)
 
void * stk_sequence_iterator_prev (stk_sequence_iterator_t *seqiter)
 
stk_ret stk_sequence_iterator_copy_data (stk_sequence_iterator_t *seqiter, void *data_ptr, stk_uint64 sz)
 
stk_uint64 stk_sequence_iterator_data_size (stk_sequence_iterator_t *seqiter)
 
stk_uint64 stk_sequence_iterator_alloc_size (stk_sequence_iterator_t *seqiter)
 
stk_ret stk_sequence_iterator_set_size (stk_sequence_iterator_t *seqiter, stk_uint64 sz)
 
stk_ret stk_sequence_iterator_set_user_type (stk_sequence_iterator_t *seqiter, stk_uint64 user_type)
 
stk_ret stk_sequence_find_data_by_type (stk_sequence_t *seq, stk_uint64 user_type, void **data_ptr, stk_uint64 *sz)
 
stk_ret stk_sequence_find_meta_data_by_type (stk_sequence_t *seq, stk_uint64 user_type, void **data_ptr, stk_uint64 *sz)
 

Detailed Description

This file contains the implementation of the Sequence object. The Sequence object is the center of the Sequence Toolkit API. Sequence objects are passed between every module in the system and the APIs in this module make it possible. Sequencing objects are used to pass data between services. All data communication between services are implemented by passing Sequence object with the data and meta data in them.

Function Documentation

stk_sequence_id stk_acquire_sequence_id ( stk_env_t env,
stk_service_type  type 
)

Acquire a sequence ID from the STK environment.

Sequence ID's are currently generated by using rand(), but in the future will be managed per type of service. A sequence ID is atomic so the stkenv must be passed in to both acquire and release an ID

See Also
stk_release_sequence_id()
stk_ret stk_add_reference_to_sequence ( stk_sequence_t seq,
void *  data_ptr,
stk_uint64  sz,
stk_uint64  user_type 
)

Add some referenced data to the sequence.

The sequence, data pointer and size must all be non-null or non-0.

The data is NOT copied - it is the application responsibility to ensure the integrity of data is maintained between this function being called and when other functions use this sequence. I.E. The API's don't provide thread safety for the data

This API is specifically designed to allow you to reuse a sequence while data is changed, but it is recommended you call stk_update_ref_data_in_sequence() before updating data to ensure data archiving can occur as needed.

Returns
Whether the reference was successfully added to the Sequence
stk_ret stk_add_sequence_reference_in_sequence ( stk_sequence_t seq,
stk_sequence_t merge_seq,
stk_uint64  user_type 
)

Add a sequence (merge_seq) to another sequence as a reference

Using stk_iterate_sequence() will allow both sequences to be iterated over seemlessly. Thus, sending sequences will effectively merge them and the receiving system will see one large sequence.

The sequences, data pointer and size must all be non-null or non-0.

The merging sequence is NOT copied - it is the application responsibility to ensure the integrity of data is maintained between this function being called and when other functions use this sequence. I.E. The API's don't provide thread safety for the data

This API is specifically designed to allow you to manage multiple sequences as one.

Returns
Whether the sequence reference was successfully added to the Sequence
stk_ret stk_alloc_in_sequence ( stk_sequence_t seq,
stk_uint64  sz,
stk_uint64  user_type 
)

Allocate a sequence element at the end of the sequence

Returns
Whether the element was allocated or not
stk_generation_id stk_bump_sequence_generation ( stk_sequence_t seq)

Bump the generation ID of a sequence. This is used by data flow modules when sending sequences

Returns
The old generation
stk_ret stk_copy_to_sequence ( stk_sequence_t seq,
void *  data_ptr,
stk_uint64  sz,
stk_uint64  user_type 
)

Copy some data to the sequence. The sequence, data pointer and size must all be non-null or non-0

Returns
Whether the data was successfully copied to the Sequence
stk_ret stk_copy_to_sequence_meta_data ( stk_sequence_t seq,
void *  data_ptr,
stk_uint64  sz,
stk_uint64  user_type 
)

Copy some data to the sequence meta data. The sequence, data pointer and size must all be non-null or non-0

Sequence meta data is considered local data and for example is not transmitted by data flows. Meta data is managed independently and uses separate APIs for adding/finding data in sequences.

Returns
Whether the data was successfully copied to the Sequence
stk_sequence_t* stk_create_sequence ( stk_env_t env,
char *  name,
stk_sequence_id  id,
stk_sequence_type  type,
stk_service_type  svctype,
stk_options_t options 
)

Create a sequence object.

Only the stk_env is mandatory.

The name is copied and may be freed by the application.

Use NULL or STK_SEQUENCE_ID_INVALID to get default values for name and id. Default Sequence ID's are allocated/released calling stk_acquire_sequence_id() and stk_release_sequence_id(). There are no invalid values for type or svctype. Rapid reuse of the same ID is not supported - always create

Returns
An allocated object. Free with stk_destroy_sequence()
See Also
stk_acquire_sequence_id()
stk_ret stk_destroy_sequence ( stk_sequence_t seq)

Destroy an allocated sequence object.

Returns
Whether the Sequence was successfully destroyed
stk_ret stk_end_sequence_iterator ( stk_sequence_iterator_t seqiter)

Frees the iterator

Returns
Whether the iterator was successfully freed.
stk_env_t* stk_env_from_sequence ( stk_sequence_t seq)

Get the STK Environment from a Sequence

Returns
The environment which a sequence is associated with.
stk_generation_id stk_get_sequence_generation ( stk_sequence_t seq)

API to get a sequences generation

stk_sequence_id stk_get_sequence_id ( stk_sequence_t seq)

API to return the ID of a sequence

Returns
The ID of the Sequence
See Also
stk_create_sequnce()
char* stk_get_sequence_name ( stk_sequence_t seq)

API to get the name of a sequence.

Returns
The name of the sequence or NULL
stk_sequence_type stk_get_sequence_type ( stk_sequence_t seq)

API to return the Type of a sequence

Returns
The Type of the Sequence
See Also
stk_create_sequence()
int stk_has_any_sequence_elements ( stk_sequence_t seq)

API to determine if a sequence has any elements

Returns
0 if there are no elements, 1 if there are some elements
void stk_hold_sequence ( stk_sequence_t seq)

Hold a sequence - this increments a reference count. Use stk_destroy_sequence() to relinquish the hold.

See Also
stk_destroy_sequence
stk_ret stk_iterate_complete_sequence ( stk_sequence_t seq,
stk_sequence_cb  before_cb,
stk_sequence_cb  element_cb,
stk_sequence_cb  after_cb,
void *  clientd 
)

API to execute a callback before iterating over elements, on each element in a sequence, and after.

The sequence (seq) may be a sequence or a sequence iterator (casted).

Use of an iterator allows the callback use of other iterator APIs.

Passing an iterator and using a merged sequence is not supported.

Returns
STK_SUCCESS if all the elements were iterated over (a callback returning failure halts iteration, after_cb is still called)
stk_ret stk_iterate_sequence ( stk_sequence_t seq,
stk_sequence_cb  element_cb,
void *  clientd 
)

API to execute a callback on each element in a sequence.

The sequence (seq) may be a sequence or a sequence iterator (casted).

Use of an iterator allows the callback use of other iterator APIs.

Passing an iterator and using a merged sequence is not supported.

Returns
STK_SUCCESS if all the elements were iterated over (a callback returning failure halts iteration)
void* stk_last_sequence_element ( stk_sequence_t seq)

API to get the last data element in the sequence (Useful when appending data)

Returns
A pointer to the last element data
int stk_number_of_sequence_elements ( stk_sequence_t seq)

API to determine the number of elements in a sequence

Note, if a merged sequence exists, the total count will be returned.

Returns
The total number of elements in the sequence
stk_ret stk_release_sequence_id ( stk_env_t env,
stk_sequence_id   
)

Release a sequence ID from the STK environment. A sequence ID is atomic so the stkenv must be passed in to both acquire and release an ID

stk_uint64 stk_remove_sequence_data_by_type ( stk_sequence_t seq,
stk_uint64  user_type,
stk_uint64  max_instances 
)

Remove up to N instances of data of "user_type" from the sequence

Parameters
seqThe sequence to have items removed from
user_typeThe user type of the sequence element to be removed
max_instancesThe number of instances to be removed (or 0 for all [may be performance impacting])
Returns
The number of instances removed
stk_ret stk_sequence_find_data_by_type ( stk_sequence_t seq,
stk_uint64  user_type,
void **  data_ptr,
stk_uint64 sz 
)

API to find an element by user type. Use of this API likely leads to slower applications if used repeatedly. When searching for more than one item, use an iterator.

Returns
STK_SUCCESS if the user type was found or an error (E.G STK_NOT_FOUND if not)
stk_ret stk_sequence_find_meta_data_by_type ( stk_sequence_t seq,
stk_uint64  user_type,
void **  data_ptr,
stk_uint64 sz 
)

API to find an element by user type in the meta data.

Returns
STK_SUCCESS if the user type was found or an error (E.G STK_NOT_FOUND if not)
stk_sequence_iterator_t* stk_sequence_iterator ( stk_sequence_t seq)

Create an iterator for a sequence. Note a sequence can not be changed while using an iterator on it.

Note: this iterator does not support iterating over merged sequences. The merged sequences will be skipped. Use stk_iterate_sequence() instead.

Returns
a handle to an iterator for the given Sequence
See Also
stk_end_sequence_iterator()
stk_uint64 stk_sequence_iterator_alloc_size ( stk_sequence_iterator_t seqiter)

Get the allocated size of the iterator's current sequence element

Returns
the allocated size (0 if not allocated)
stk_ret stk_sequence_iterator_copy_data ( stk_sequence_iterator_t seqiter,
void *  data_ptr,
stk_uint64  sz 
)

API to copy data in to an existing sequence element based on the current iterators position

Returns
SUCCESS if data is copied, otherwise the data buffer is too small or there is no current object in the iterator
void* stk_sequence_iterator_data ( stk_sequence_iterator_t seqiter)

API to return the current data item

Returns
the current data item pointed to by the iterator.
stk_uint64 stk_sequence_iterator_data_size ( stk_sequence_iterator_t seqiter)

Get the size of the iterator's current sequence element

Returns
The data size
void* stk_sequence_iterator_ensure_segment_size ( stk_sequence_iterator_t seqiter,
stk_uint64  sz 
)

API to ensure a segment is a specific size, realloc'ing it if necessary.

Returns
The data pointer sized at the requested size (may be the same or different)
void* stk_sequence_iterator_next ( stk_sequence_iterator_t seqiter)

API to move the iterator to the next Sequence.

Returns
the next data item pointed to by the iterator. Returns NULL at end, then wraps.
void* stk_sequence_iterator_prev ( stk_sequence_iterator_t seqiter)

API to move the iterator to the previous Sequence.

Returns
the previous data item pointed to by the iterator. Returns NULL at the start, then wraps.
void* stk_sequence_iterator_realloc_segment ( stk_sequence_iterator_t seqiter,
stk_uint64  sz 
)

API to realloc the iterators current data buffer

Returns
The newly allocated data pointer (may be the same)
stk_ret stk_sequence_iterator_set_size ( stk_sequence_iterator_t seqiter,
stk_uint64  sz 
)

API to set the size of the data in the current sequence element.

Can't be bigger than the allocated size of the buffer

Returns
STK_SUCCESS if the data size was set.
stk_ret stk_sequence_iterator_set_user_type ( stk_sequence_iterator_t seqiter,
stk_uint64  user_type 
)

API to set the current sequence elements user type.

Returns
STK_SUCCESS if the data size was set.
stk_ret stk_set_sequence_id ( stk_sequence_t seq,
stk_sequence_id  id 
)

API to set the ID of a sequence.

Returns
Whether the ID was set
stk_ret stk_set_sequence_name ( stk_sequence_t seq,
char *  name 
)

API to set the Name of a sequence. This name should be dynamically allocated as stk_destroy_sequence() will free it.

Returns
Whether the Name was set
stk_ret stk_set_sequence_type ( stk_sequence_t seq,
stk_sequence_type  type 
)

API to set the Type of a sequence.

Returns
Whether the Type was set
stk_ret stk_update_ref_data_in_sequence ( stk_sequence_t seq,
stk_generation_id gen_id 
)

stk_update_ref_data_in_sequence() updates the data generation of a sequence and copies reference data if there are references to it for archival purposes. For most efficiency, this API should be called when ready to modify data. [Not implemented]

Returns
the generation ID of data archived in gen_id if not NULL