Data Memory Vectors

Structure for storing a linear and compact array of values. More...

Collaboration diagram for Data Memory Vectors:

Data Structures
struct	MDATA_VECTOR
	A vector of uniformly-sized objects, stored contiguously. More...

Macros
#define	MDATA_VECTOR_FLAG_REFCOUNT   0x01
	Flag for MDATA_VECTOR::flags indicating that vector may uses reference counting for locking.
#define	MDATA_VECTOR_FLAG_IS_LOCKED   0x02
#define	MDATA_VECTOR_INIT_STEP_SZ   10
	Default initial value for MDATA_VECTOR::ct_step.
#define	mdata_vector_lock(v)
	Lock the vector. This should be done when items from the vector are actively being referenced, so the system is not allowed to move the vector's data allocation block.
#define	mdata_vector_unlock(v)
	Unlock the vector so items may be added and removed.
#define	mdata_vector_get(v, idx, type)
#define	mdata_vector_get_last(v, type)
#define	mdata_vector_remove_last(v)
#define	mdata_vector_set_ct_step(v, step)
#define	mdata_vector_ct(v)
	Number of items of MDATA_VECTOR::item_sz bytes actively stored in this vector.
#define	mdata_vector_sz(v)
	Number of bytes of heap memory occupied by this vector.
#define	mdata_vector_fill(v, ct_new, sz)
	Allocate and mark the new slots as active.
#define	mdata_vector_is_locked(v)
#define	mdata_vector_insert_sort(v, i, t, field)
#define	mdata_vector_sort(v, t, field)
#define	_mdata_vector_item_ptr(v, idx)
#define	mdata_vector_set_flag(v, flag)
#define	mdata_vector_get_flag(v, flag)

Functions
ssize_t	mdata_vector_insert (struct MDATA_VECTOR *v, const void *item, ssize_t idx, size_t item_sz)
MERROR_RETVAL	mdata_vector_copy (struct MDATA_VECTOR *v_dest, struct MDATA_VECTOR *v_src)
MERROR_RETVAL	mdata_vector_alloc (struct MDATA_VECTOR *v, size_t item_sz, size_t item_ct_init)
void	mdata_vector_free (struct MDATA_VECTOR *v)
ssize_t	mdata_vector_append (struct MDATA_VECTOR *v, const void *item, size_t item_sz)
	Append an item to the specified vector.
MERROR_RETVAL	mdata_vector_remove (struct MDATA_VECTOR *v, size_t idx)
	Remove item at the given index, shifting subsequent items up by 1.
void *	mdata_vector_get_void (const struct MDATA_VECTOR *v, size_t idx)
	Get a generic pointer to an item in the MDATA_VECTOR.

Detailed Description

Structure for storing a linear and compact array of values.

Macro Definition Documentation

_mdata_vector_item_ptr

#define _mdata_vector_item_ptr	(		v,
			idx )

Value:

   (&((v)->data_bytes[((idx) * ((v)->item_sz))]))

mdata_vector_ct

#define mdata_vector_ct ( v )

related

Value:

((v)->ct)

Number of items of MDATA_VECTOR::item_sz bytes actively stored in this vector.

Warning

This is not neccessarily equal to amount of memory occupied by the vector, as it may have allocated more than are currently occupied!

mdata_vector_fill

#define mdata_vector_fill ( v, ct_new, sz )

related

Value:

   retval = mdata_vector_alloc( v, sz, ct_new ); \
   maug_cleanup_if_not_ok(); \
   (v)->ct = (ct_new);

Allocate and mark the new slots as active.

MDATA_VECTOR_FLAG_REFCOUNT

#define MDATA_VECTOR_FLAG_REFCOUNT   0x01

related

Flag for MDATA_VECTOR::flags indicating that vector may uses reference counting for locking.

Such a mobile may be locked multiple times, but then must be unlocked an equal number of times to unlock.

mdata_vector_get

#define mdata_vector_get	(		v,
			idx,
			type )

Value:

   ((type*)mdata_vector_get_void( v, idx ))

mdata_vector_get_flag

#define mdata_vector_get_flag	(		v,
			flag )

Value:

((flag) == ((v)->flags & (flag)))

mdata_vector_get_last

#define mdata_vector_get_last	(		v,
			type )

Value:

   (0 < mdata_vector_ct( v ) ? \
      ((type*)mdata_vector_get_void( v, \
         mdata_vector_ct( v ) - 1 )) : NULL)

mdata_vector_is_locked

#define mdata_vector_is_locked

(

v

)

Value:

   (MDATA_VECTOR_FLAG_IS_LOCKED == \
   (MDATA_VECTOR_FLAG_IS_LOCKED & (v)->flags))

mdata_vector_lock

#define mdata_vector_lock ( v )

related

Value:

   if( (MAUG_MHANDLE)NULL == (v)->data_h && NULL == (v)->data_bytes ) { \
      mdata_debug_printf( "locking empty vector..." ); \
      (v)->flags |= MDATA_VECTOR_FLAG_IS_LOCKED; \
   } else if( \
      mdata_vector_get_flag( v, MDATA_VECTOR_FLAG_REFCOUNT ) && \
      0 < (v)->locks \
   ) { \
      (v)->locks++; \
      mdata_debug_printf( "vector " #v " locks: " SSIZE_T_FMT, (v)->locks ); \
   } else { \
      /* assert( !mdata_vector_is_locked( v ) ); */ \
      if( mdata_vector_is_locked( v ) ) { \
         error_printf( "attempting to double-lock vector!" ); \
         retval = MERROR_OVERFLOW; \
         goto cleanup; \
      } \
      if( (MAUG_MHANDLE)NULL == (v)->data_h ) { \
         error_printf( "invalid data handle!" ); \
         retval = MERROR_ALLOC; \
         goto cleanup; \
      } \
      maug_mlock( (v)->data_h, (v)->data_bytes ); \
      maug_cleanup_if_null_lock( uint8_t*, (v)->data_bytes ); \
      (v)->flags |= MDATA_VECTOR_FLAG_IS_LOCKED; \
      mdata_debug_printf( "locked vector " #v ); \
   }

Lock the vector. This should be done when items from the vector are actively being referenced, so the system is not allowed to move the vector's data allocation block.

Warning

mdata_vector_lock() should never be called after the cleanup label! (This is fine for mdata_vector_unlock(), however.)

mdata_vector_remove_last

#define mdata_vector_remove_last

(

v

)

Value:

   (0 < mdata_vector_ct( v ) ? \
      (mdata_vector_remove( v, mdata_vector_ct( v ) - 1 )) : MERROR_OVERFLOW)

mdata_vector_set_ct_step

#define mdata_vector_set_ct_step	(		v,
			step )

Value:

   (v)->ct_step = step;

mdata_vector_set_flag

#define mdata_vector_set_flag	(		v,
			flag )

Value:

(v)->flags |= (flag)

mdata_vector_sz

#define mdata_vector_sz ( v )

related

Value:

(((v)->ct_max) * ((v)->item_sz))

Number of bytes of heap memory occupied by this vector.

mdata_vector_unlock

#define mdata_vector_unlock ( v )

related

Value:

   if( (MAUG_MHANDLE)NULL == (v)->data_h && NULL == (v)->data_bytes ) { \
      mdata_debug_printf( "locking empty vector..." ); \
      (v)->flags &= ~MDATA_VECTOR_FLAG_IS_LOCKED; \
   } else { \
      if( \
         mdata_vector_get_flag( v, MDATA_VECTOR_FLAG_REFCOUNT ) && \
         0 < (v)->locks \
      ) { \
         (v)->locks--; \
         mdata_debug_printf( "vector " #v " locks: " SSIZE_T_FMT, \
            (v)->locks ); \
      } \
      if( 0 == (v)->locks && NULL != (v)->data_bytes ) { \
         assert( mdata_vector_is_locked( v ) ); \
         maug_munlock( (v)->data_h, (v)->data_bytes ); \
         (v)->flags &= ~MDATA_VECTOR_FLAG_IS_LOCKED; \
         mdata_debug_printf( "unlocked vector " #v ); \
      } \
   }

Unlock the vector so items may be added and removed.

Note

mdata_vector_unlock() may be called after the cleanup label.

Function Documentation

mdata_vector_alloc()

MERROR_RETVAL mdata_vector_alloc	(	struct MDATA_VECTOR *	v,
		size_t	item_sz,
		size_t	item_ct_init )

Warning

The vector must not be locked before an append or allocate! Reallocation could change pointers gotten during a lock!

mdata_vector_append()

ssize_t mdata_vector_append ( struct MDATA_VECTOR * v, const void * item, size_t item_sz )

related

Append an item to the specified vector.

Parameters

v	The vector to append to.
item	The address of an item to copy to the newly-created vector slow, or NULL to not copy anything.
item_sz	Size (in bytes) of the item to append. If the item is sized differently from the first item appended, MERROR_OVERFLOW will be returned and the item will not be appended.

Returns

Index of the appended item or MERROR_RETVAL * -1 if append fails.

Warning

The vector must not be locked before an append or allocate! Reallocation could change pointers gotten during a lock!

mdata_vector_get_void()

void * mdata_vector_get_void ( const struct MDATA_VECTOR * v, size_t idx )

related

Get a generic pointer to an item in the MDATA_VECTOR.

Parameters

v	Vector to request the item from. Should be locked!
idx	Index of item to retrieve.

Returns

Return a generic pointer to the item at the requested index, or NULL if the index is outside of the vector bounds.

mdata_vector_remove()

MERROR_RETVAL mdata_vector_remove ( struct MDATA_VECTOR * v, size_t idx )

related

Remove item at the given index, shifting subsequent items up by 1.

Warning

The vector must not be locked before a removal!