|
The Sequence Toolkit
www.sequence-toolkit.com |
|
The Sequence Toolkit
www.sequence-toolkit.com |
Go to the source code of this file.
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.
| 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
| 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.
| 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.
| 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
| 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
| 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
| 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.
| 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
| stk_ret stk_destroy_sequence | ( | stk_sequence_t * | seq | ) |
Destroy an allocated sequence object.
| stk_ret stk_end_sequence_iterator | ( | stk_sequence_iterator_t * | seqiter | ) |
Frees the iterator
| stk_env_t* stk_env_from_sequence | ( | stk_sequence_t * | seq | ) |
Get the STK Environment from a Sequence
| 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
| char* stk_get_sequence_name | ( | stk_sequence_t * | seq | ) |
API to get the name of a sequence.
| stk_sequence_type stk_get_sequence_type | ( | stk_sequence_t * | seq | ) |
| int stk_has_any_sequence_elements | ( | stk_sequence_t * | seq | ) |
API to determine if a sequence has any 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.
| 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.
| 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.
| void* stk_last_sequence_element | ( | stk_sequence_t * | seq | ) |
API to get the last data element in the sequence (Useful when appending 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.
| 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
| seq | The sequence to have items removed from |
| user_type | The user type of the sequence element to be removed |
| max_instances | The number of instances to be removed (or 0 for all [may be performance impacting]) |
| 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.
| 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.
| 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.
| stk_uint64 stk_sequence_iterator_alloc_size | ( | stk_sequence_iterator_t * | seqiter | ) |
Get the allocated size of the iterator's current sequence element
| 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
| void* stk_sequence_iterator_data | ( | stk_sequence_iterator_t * | seqiter | ) |
API to return the current data item
| stk_uint64 stk_sequence_iterator_data_size | ( | stk_sequence_iterator_t * | seqiter | ) |
Get the size of the iterator's current sequence element
| 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.
| void* stk_sequence_iterator_next | ( | stk_sequence_iterator_t * | seqiter | ) |
API to move the iterator to the next Sequence.
| void* stk_sequence_iterator_prev | ( | stk_sequence_iterator_t * | seqiter | ) |
API to move the iterator to the previous Sequence.
| void* stk_sequence_iterator_realloc_segment | ( | stk_sequence_iterator_t * | seqiter, |
| stk_uint64 | sz | ||
| ) |
API to realloc the iterators current data buffer
| 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
| 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.
| stk_ret stk_set_sequence_id | ( | stk_sequence_t * | seq, |
| stk_sequence_id | id | ||
| ) |
API to set the ID of a sequence.
| 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.
| stk_ret stk_set_sequence_type | ( | stk_sequence_t * | seq, |
| stk_sequence_type | type | ||
| ) |
API to set the Type of a sequence.
| 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]
