Difference between pages "r6.1.1:Lfds611 freelist new elements" and "r6.1.1:Lfds611 freelist pop"

From liblfds.org
(Difference between pages)
Jump to navigation Jump to search
m (1 revision imported)
 
m (1 revision imported)
 
Line 1: Line 1:
{{DISPLAYTITLE:r6.1.1:lfds611_freelist_new_elements}}
{{DISPLAYTITLE:r6.1.1:lfds611_freelist_pop}}
==Source Files==
==Source Files==
  /liblfds611/src/lfds611_freelist/lfds611_freelist_new.c
  /liblfds611/src/lfds611_freelist/lfds611_freelist_pop_push.c
  /liblfds611/inc/liblfds611.h
  /liblfds611/inc/liblfds611.h


==Prototype==
==Prototype==
  lfds611_atom_t lfds611_freelist_new_elements( struct lfds611_freelist_state *fs, lfds611_atom_t number_elements );
  struct lfds611_freelist_element *lfds611_freelist_pop( struct lfds611_freelist_state *fs, struct lfds611_freelist_element **fe );


==Parameters==
==Parameters==
Line 11: Line 11:
: A freelist state as allocated by ''[[r6.1.1:lfds611_freelist_new|lfds611_freelist_new]]''.
: A freelist state as allocated by ''[[r6.1.1:lfds611_freelist_new|lfds611_freelist_new]]''.


''lfds611_atom_t number_elements''
''struct lfds611_freelist_element **fe''
: The number of additional elements to add to the freelist.
: A pointer to a freelist element pointer which will be set to point to a ''struct freelist'' popped from the freelist.  Set to NULL if the freelist is empty.


==Return Value==
==Return Value==
The number of elements added to the freelist.
Returns a pointer to the freelist element (e.g. the value ''*fe'' is set to).  If the freelist is empty, the return value is NULL and ''*lfds611_freelist_element'' is set to NULL.  In this case, the user can call, the caller can call ''[[r6.1.1:lfds611_freelist_guaranteed_pop|lfds611_freelist_guaranteed_pop]]'', which will allocate a new element, rather than popping from the freelist.  Remember however that the freelist can never shrink, so any such call will permanently increase the size of the freelist by one element.


==Notes==
==Notes==
This function creates a new freelist element and adds it to the freelist, repeating this process ''number_elements'' times.  Each element will be passed to the ''user_data_init_function'' function passed into the ''lfds611_freelist_new'' function. That function will also be passed the ''user_state'' argument which was provided to ''lfds611_freelist_new''.  If element creation fails (will can be only due to memory allocation failure or failure of the user initialisation function), that element will not be created and so the number of elements actually added to the freelist will be less than the requested number.
Popping returns to the user a freelist element.  To obtain the user data void pointer from the element, use ''[[r6.1.1:lfds611_freelist_get_user_data_from_element|lfds611_freelist_get_user_data_from_element]]''.
 
This function is thread-safe; it can be used in parallel with other functions adding new elements and with pushing and popping.


==See Also==
==See Also==
* [[r6.1.1:lfds611_freelist|lfds611_freelist]]
* [[r6.1.1:lfds611_freelist|lfds611_freelist]]
* [[r6.1.1:lfds611_freelist_push|lfds611_freelist_push]]

Latest revision as of 14:07, 4 January 2015

Source Files

/liblfds611/src/lfds611_freelist/lfds611_freelist_pop_push.c
/liblfds611/inc/liblfds611.h

Prototype

struct lfds611_freelist_element *lfds611_freelist_pop( struct lfds611_freelist_state *fs, struct lfds611_freelist_element **fe );

Parameters

struct lfds611_freelist_state *fs

A freelist state as allocated by lfds611_freelist_new.

struct lfds611_freelist_element **fe

A pointer to a freelist element pointer which will be set to point to a struct freelist popped from the freelist. Set to NULL if the freelist is empty.

Return Value

Returns a pointer to the freelist element (e.g. the value *fe is set to). If the freelist is empty, the return value is NULL and *lfds611_freelist_element is set to NULL. In this case, the user can call, the caller can call lfds611_freelist_guaranteed_pop, which will allocate a new element, rather than popping from the freelist. Remember however that the freelist can never shrink, so any such call will permanently increase the size of the freelist by one element.

Notes

Popping returns to the user a freelist element. To obtain the user data void pointer from the element, use lfds611_freelist_get_user_data_from_element.

See Also

Retrieved from ‘https://www.liblfds.org/mediawiki/index.php?title=r6.1.1:Lfds611_freelist_new_elements&oldid=370’