RaftLib  0.3a
C++ Stream Processing Template Library
Classes | Public Member Functions | Protected Types | Protected Member Functions | Friends | List of all members
FIFO Class Referenceabstract

Public Member Functions

 FIFO ()
 
virtual ~FIFO ()
 
virtual std::size_t size ()=0
 
virtual std::size_t space_avail ()=0
 
virtual std::size_t capacity ()=0
 
template<class T , typename std::enable_if< std::is_pod< T >::value >::type * = nullptr>
T & allocate ()
 
template<class T , class... Args, typename std::enable_if< std::is_object< T >::value and notstd::is_fundamental< T >::value >::type * = nullptr>
T & allocate (Args &&...params)
 
virtual void deallocate ()=0
 
template<class T >
auto allocate_s () -> autorelease< T, allocatetype >
 
template<class T >
auto allocate_range (const std::size_t n) -> std::vector< std::reference_wrapper< T > >
 
virtual void send (const raft::signal=raft::none)=0
 
virtual void send_range (const raft::signal=raft::none)=0
 
template<class T >
void push (const T &item, const raft::signal signal=raft::none)
 
template<class T >
void push (T &&item, const raft::signal signal=raft::none)
 
template<class iterator_type >
void insert (iterator_type begin, iterator_type end, const raft::signal signal=raft::none)
 
template<class T >
void pop (T &item, raft::signal *signal=nullptr)
 
template<class T >
void pop_range (pop_range_t< T > &items, const std::size_t n_items)
 
template<class T >
T & peek (raft::signal *signal=nullptr)
 
template<class T >
auto peek_range (const std::size_t n) -> autorelease< T, peekrange >
 
virtual void unpeek ()=0
 
template<class T , typename std::enable_if< std::is_pod< T >::value >::type * = nullptr>
void recycle (const T &t, const std::size_t range=1)
 
template<class T , typename std::enable_if< std::is_object< T >::value and notstd::is_fundamental< T >::value >::type * = nullptr>
void recycle (const T &t, const std::size_t range=1)
 
virtual void get_zero_read_stats (Blocked &copy)
 
virtual void get_zero_write_stats (Blocked &copy)
 
virtual void resize (const std::size_t n_items, const std::size_t align, volatile bool &exit_alloc)=0
 
virtual float get_frac_write_blocked ()=0
 
virtual void invalidate ()=0
 
virtual bool is_invalid ()=0
 

Protected Types

using recyclefunc = std::function< void(void *) >
 

Protected Member Functions

virtual void set_src_kernel (raft::kernel *const k)=0
 
virtual void set_dst_kernel (raft::kernel *const k)=0
 
virtual raft::signal signal_peek ()=0
 
virtual void signal_pop ()=0
 
virtual void inline_signal_send (const raft::signal sig)=0
 
virtual void local_allocate (void **ptr)=0
 
virtual void local_allocate_n (void *ptr, const std::size_t n)=0
 
virtual void local_push (void *ptr, const raft::signal &signal)=0
 
virtual void local_insert (void *ptr_begin, void *ptr_end, const raft::signal &signal, const std::size_t iterator_type)=0
 
virtual void local_pop (void *ptr, raft::signal *signal)=0
 
virtual void local_pop_range (void *ptr_data, std::size_t n_items)=0
 
virtual void local_peek (void **ptr, raft::signal *signal)=0
 
virtual void local_peek_range (void **ptr, void **sig, const std::size_t n_items, std::size_t &curr_pointer_loc)=0
 
virtual void local_recycle (const std::size_t range)=0
 
virtual void local_recycle (const std::size_t range, recyclefunc func)=0
 

Friends

class Schedule
 
class Allocate
 

Constructor & Destructor Documentation

FIFO::FIFO ( )

FIFO - default constructor for base class for all subsequent ringbuffers.

FIFO.cpp -

Author
: Jonathan Beard
Version
: Thu Sep 4 12:59:45 2014

Copyright 2014 Jonathan Beard

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

FIFO::~FIFO ( )
virtual

~FIFO - default destructor

Member Function Documentation

template<class T , typename std::enable_if< std::is_pod< T >::value >::type * = nullptr>
T& FIFO::allocate ( )
inline

allocate - returns a reference to a writeable member at the tail of the FIFO. You must have a subsequent call to send in order to release this object to the FIFO once it is written. If the user needs to de-allocate the memory without using it, they can call the deallocate function.

Returns
T&

call blocks till an element is available

Here is the call graph for this function:

template<class T , class... Args, typename std::enable_if< std::is_object< T >::value and notstd::is_fundamental< T >::value >::type * = nullptr>
T& FIFO::allocate ( Args &&...  params)
inline

call blocks till an element is available

Here is the call graph for this function:

template<class T >
auto FIFO::allocate_range ( const std::size_t  n) -> std::vector< std::reference_wrapper< T > >
inline

TODO, fix allocate_range to double buffer properly if not enough mem available allocate_range - returns a std::vector of references to n items on the queue. If for some reason the capacity of the queue is less than n or some other unspecified error occurs then the number allocated is returned in n_ret. To release items to the queue, use push_range as opposed to the standard push.

Parameters
n- const std::size_t, # items to allocate
Returns
std::vector< std::reference_wrapper< T > >

compiler should optimize this copy, if not then it'll be a copy of referneces not full objects

Here is the call graph for this function:

template<class T >
auto FIFO::allocate_s ( ) -> autorelease< T, allocatetype >
inline

allocate_s - "auto-release" version of allocate, where the action of pushing the memory allocated to the consumer is handled by the returned object exiting the calling stack frame.

Returns
autorelease< T, allocatetype >

Here is the call graph for this function:

virtual std::size_t FIFO::capacity ( )
pure virtual

capacity - returns the set maximum capacity of the FIFO.

Returns
std::size_t
virtual void FIFO::deallocate ( )
pure virtual

deallocate - call after allocate if memory allocated is not needed. Will deallocate all memory allocated by a previous allocate call.

virtual float FIFO::get_frac_write_blocked ( )
pure virtual

get_frac_write_blocked - returns the fraction of time that this queue was blocked. This might become a private function accessible only to the dynamic allocator mechanism, but for now its a public function.

Returns
float

Here is the caller graph for this function:

void FIFO::get_zero_read_stats ( Blocked copy)
virtual

get_zero_read_stats - sets the param variable to the current blocked stats and then sets the current vars to zero. Default version here does nothing, when instrumentation is enabled then the function called actually does something.

Parameters
copy- Blocked&

default version does nothing at all

void FIFO::get_zero_write_stats ( Blocked copy)
virtual

get_zero_write_stats - sets the param variable to the current blocked stats and then sets the current vars to zero. Default version here does nothing, when instrumentation is enabled then the function, called actually does something.

Parameters
copy- Blocked&

default version does nothing at all

virtual void FIFO::inline_signal_send ( const raft::signal  sig)
protectedpure virtual

inline_signal_send - pretty much exactly like it sounds, the implementations of this function must pass a signal inline with the data stream so that this signal is received immediately after the data element sent before it.

Parameters
sig- raft::signal, signal to be sent
template<class iterator_type >
void FIFO::insert ( iterator_type  begin,
iterator_type  end,
const raft::signal  signal = raft::none 
)
inline

insert - inserts the range from begin to end in the FIFO, blocks until space is available. If the range is greater than the space available it'll simply block and add items as space becomes available. There is the implicit assumption that another thread is consuming the data, so eventually there will be room.

Parameters
begin- iterator_type, iterator to begin of range
end- iterator_type, iterator to end of range
signal- raft::signal, default raft::none

Here is the call graph for this function:

virtual void FIFO::invalidate ( )
pure virtual

invalidate - used by producer thread to label this queue as invalid. Could be for many differing reasons, however the bottom line is that once empty, this queue will receive no extra data and the receiver must do something to deal with this type of behavior if more data is requested.

Here is the caller graph for this function:

virtual bool FIFO::is_invalid ( )
pure virtual

is_invalid - called by the consumer thread to check if this queue is in fact valid. This is typically only called if the queue is empty or if the consumer is asking for more data than is currently available.

Returns
bool - true if invalid
virtual void FIFO::local_allocate ( void **  ptr)
protectedpure virtual

local_allocate - in order to get this whole thing to work with multiple "ports" contained within the same container we have to erase the type and then put it back. To do this the template function gives a void ptr mem address which is given the location to the head of the queue. Once returned the main allocate function reinterprets this as the proper object type

Parameters
ptr- void **

Here is the caller graph for this function:

virtual void FIFO::local_allocate_n ( void *  ptr,
const std::size_t  n 
)
protectedpure virtual

local_allocate_n - copies std::ref's to the data structure passed in by ptr.

Parameters
-ptr, void* dereferenced std::vector
-n, const std::size_t

Here is the caller graph for this function:

virtual void FIFO::local_insert ( void *  ptr_begin,
void *  ptr_end,
const raft::signal &  signal,
const std::size_t  iterator_type 
)
protectedpure virtual

local_insert - inserts a range from ptr_begin to ptr_end and inserts the signal at the last element inserted, the rest of the signals are set to raft::none.

Parameters
ptr_begin- void*
ptr_end- void*
signal- const raft::signal&

Here is the caller graph for this function:

virtual void FIFO::local_peek ( void **  ptr,
raft::signal *  signal 
)
protectedpure virtual

local_peek - peeks at the head of the queue, the element may be modified but not erased.

Parameters
ptr- void**
signal- raft::signal*

Here is the caller graph for this function:

virtual void FIFO::local_peek_range ( void **  ptr,
void **  sig,
const std::size_t  n_items,
std::size_t &  curr_pointer_loc 
)
protectedpure virtual

local_peek_range - peeks at head of queue with the specified range, data may be modified but not erased. Since the queue might be non-contiguous then we must return the memory location of each element.

Parameters
ptr- void**, pointer to pointers at which to store the pointers to items on the queue
sig- void**, same as above but for signal queue
n_items- const std::size_t, number of items requested
curr_pointer_loc- number of items able to be returned

Here is the caller graph for this function:

virtual void FIFO::local_pop ( void *  ptr,
raft::signal *  signal 
)
protectedpure virtual

local_pop - makes a copy, pops an item from the queue and stores the copy at memory located at *ptr.

Parameters
ptr- void*
signal- raft::signal*

Here is the caller graph for this function:

virtual void FIFO::local_pop_range ( void *  ptr_data,
std::size_t  n_items 
)
protectedpure virtual

local_pop_range - pops a range, of n_items and stores them to the array of T* items pointed to by ptr_data.

Parameters
ptr_data- void*
n_items- std::size_t

Here is the caller graph for this function:

virtual void FIFO::local_push ( void *  ptr,
const raft::signal &  signal 
)
protectedpure virtual

local_push - pushes the object reference by the void ptr and pushes it to the FIFO with the associated signal. Once this function returns, the value is copied according to the objects copy constructor, which should be set up to "deep" copy the object

Parameters
ptr- void*
signal- raft::signal reference

Here is the caller graph for this function:

virtual void FIFO::local_recycle ( const std::size_t  range)
protectedpure virtual

local_recycle - called by template recycle function after calling destructor (for non-POD types).

Parameters
range- std::size_t

Here is the caller graph for this function:

template<class T >
T& FIFO::peek ( raft::signal *  signal = nullptr)
inline

peek - returns a reference to the head of the queue. unpeek() must be called after this to tell the runtime that the reference is no longer being used.

Parameters
signal- raft::signal, default: nullptr
Returns
T&

Here is the call graph for this function:

template<class T >
auto FIFO::peek_range ( const std::size_t  n) -> autorelease< T, peekrange >
inline

peek_range - analogous to peek, only the user gets a list of items. unpeek() must be called after using this function to let the runtime know that the user is done with the references. @ n - const std::size_t, number of items to peek

Returns
- std::vector< std::reference_wrapper< T > >

Here is the call graph for this function:

template<class T >
void FIFO::pop ( T &  item,
raft::signal *  signal = nullptr 
)
inline

pop - pops the head of the queue. If the receiving object wants to watch use the signal, then the signal parameter should not be null.

Parameters
item- T&
signal- raft::signal

Here is the call graph for this function:

template<class T >
void FIFO::pop_range ( pop_range_t< T > &  items,
const std::size_t  n_items 
)
inline

pop_range - pops n_items from the buffer into the std::vector pointed to by pop_range. There are two different ways this function could operate, either with a push_back type symantic which would mean three copies or dealing with a pre-allocated vector. This function assumes that the user has allocated a vector withthe correct size (= n_items).

Parameters
items- std::vector< std::pair< T, raft::signal > >&
n_items- std::size_t

Here is the call graph for this function:

template<class T >
void FIFO::push ( const T &  item,
const raft::signal  signal = raft::none 
)
inline

push - function which takes an object of type T and a signal, makes a copy of the object using the copy constructor and passes it to the FIFO along with the signal which is guaranteed to be delivered at the same time as the object (if of course the receiving object is responding to signals).

Parameters
item- T&
signal- raft::signal, default raft::none

call blocks till element is written and released to queue

Here is the call graph for this function:

template<class T >
void FIFO::push ( T &&  item,
const raft::signal  signal = raft::none 
)
inline

push - function which takes an object of type T and a signal, makes a copy of the object using the copy constructor and passes it to the FIFO along with the signal which is guaranteed to be delivered at the same time as the object (if of course the receiving object is responding to signals).

Parameters
item- T&&
signal- raft::signal, default raft::none

TODO, think about changing this, erasing type is always ugly

call blocks till element is written and released to queue

Here is the call graph for this function:

template<class T , typename std::enable_if< std::is_pod< T >::value >::type * = nullptr>
void FIFO::recycle ( const T &  t,
const std::size_t  range = 1 
)
inline

recycle - so you want to ignore some items from the input stream without ever even looking at them, then this is the function for you. It is also used with the peek call in order to invalidate or free memory to the queue so that the next peek or pop operation will see a a different location.

Parameters
t- refernce to object or type of object to be recycled, can be null or invalid since this function will never access it.
range- const std::size_t

Here is the call graph for this function:

virtual void FIFO::resize ( const std::size_t  n_items,
const std::size_t  align,
volatile bool &  exit_alloc 
)
pure virtual

resize - called from the dynamic allocator to resize the queue. The function itself is implemented in the various template specializations found in ringuffer.tcc. A new queue is allocated with the size specified and alignment and the old queue is copied over. The third parameter, exit_alloc must be passed from the dynamic allocator to signal with the application is finished so that the resize function doesn't wait indefinitely for queue conditions that will never arise (for exact conditions, see datamanager.tcc.

Parameters
n_items- number of items to resize q to
align- alignment of queue to allocate
exit_alloc- bool to signal when app is finished
virtual void FIFO::send ( const raft::signal  = raft::none)
pure virtual

send - releases the last item allocated by allocate() to the queue. Function will simply return if allocate wasn't called prior to calling this function.

Parameters
signal- const raft::signal, default: NONE
virtual void FIFO::send_range ( const raft::signal  = raft::none)
pure virtual

send_range - releases the items allocated by allocate_range to the queue. Function will simply return if allocate wasn't called prior to calling this function.

Parameters
signal- const raft::signal, default: NONE
virtual void FIFO::set_dst_kernel ( raft::kernel *const  k)
protectedpure virtual

set_dst_kernel - sets the protected destination kernel for this fifo, necessary for preemption, see comments on variables below.

Parameters
k- raft::kernel*

Here is the caller graph for this function:

virtual void FIFO::set_src_kernel ( raft::kernel *const  k)
protectedpure virtual

set_src_kernel - sets teh protected source kernel for this fifo, necessary for preemption, see comments on variables below.

Parameters
k- raft::kernel*

Here is the caller graph for this function:

virtual raft::signal FIFO::signal_peek ( )
protectedpure virtual

signal_peek - special function for the scheduler to peek at a signal on the head of the queue.

Returns
raft::signal
virtual void FIFO::signal_pop ( )
protectedpure virtual

signal_pop - special function fo rthe scheduler to pop the current signal and associated item.

virtual std::size_t FIFO::size ( )
pure virtual

size - returns the current size of this FIFO

Returns
std::size_t

Here is the caller graph for this function:

virtual std::size_t FIFO::space_avail ( )
pure virtual

space_avail - convenience function to get the current space available in the FIFO, could otherwise be calculated by taking the capacity() - size().

Returns
std::size_t
virtual void FIFO::unpeek ( )
pure virtual

unpeek - call after peek to let the runtime know that all references to the returned value are no longer in use. Keeps the memory location in a valid state for that input port, i.e., it doesn't release the memory location so that the next call to peek will return the same exact location. A call to recycle will release the memory, or invalidate it.

Friends And Related Function Documentation

friend class Schedule
friend

needed to keep as a friend for signalling access


The documentation for this class was generated from the following files: