Iterators - 2022.1 English

AI Engine API provides iterators to access memory successively and increasingly. There is a circular iterator that wraps around by going back to the beginning of the buffer when it reaches the end of the buffer.

aie::begin_circular

Returns a scalar circular iterator. The circular buffer size is specified.

aie::cbegin_circular

Constant version of aie::begin_circular.

aie::begin_random_circular

aie::begin_circular with random access.

aie::begin_vector

Returns a vector iterator. The elementary vector size is specified.

aie::cbegin_vector

Constant version of aie::begin_vector.

aie::begin_restrict_vector

Same as aie::begin_vector, but the return pointer is considered restrict.

aie::begin_vector_circular

Returns a vector iterator. The elementary vector size and total circular buffer size are specified.

aie::cbegin_vector_circular

Constant version of aie::begin_vector_circular.

These iterators all support:

• dereferencing *
• operator ++
• operator ==
• operator !=

Some iterators support more operators. For example, aie::begin_vector supports:

• operator --
• operator +
• operator -
• operator +=
• operator -=

aie::begin_random_circular supports:

• operator --
• operator +=
• operator -=

One of the benefits of circular buffer is that it avoids out-of-bound memory access. Following are some examples of using iterator to access memory.

alignas(aie::vector_decl_align) int32 init_value[16]={1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16};
auto pv=aie::begin_vector<4>(init_value); //create vector iterator, first value is [1,2,3,4]
auto pv_c=aie::cbegin_vector_circular<4,16>(init_value); //create const circular vector iterator, first value is [1,2,3,4], total 16 elements
for(;pv!=init_value+16;pv++){
  aie::vector<int32,4> buff=*pv;
  aie::print(*pv,true,"pv:");
  ...
}
for(int i=0;i<5;i++){
  //go back to start if reach the end of the circular buffer
  aie::vector<int32,4> buff=*pv_c++;
}
//point to circular buffer size 16.
auto p=aie::begin_circular<16>(init_value); 
for(int i=0;i<N;i++){ 
  //return back to init_value+0, if reaches init_value+16
  *p++=i;
}