NAME¶
smlist - shared memory list management library
SYNOPSIS¶
#include "smlist.h"
typedef int (*SmListCompareFn)
(PsmPartition partition, PsmAddress eltData, void *argData);
typedef void (*SmListDeleteFn)
(PsmPartition partition, PsmAddress eltData, void *argument);
[see description for available functions]
DESCRIPTION¶
The smlist library provides functions to create, manipulate and destroy
doubly-linked lists in shared memory. As with
lyst(3), smlist uses two
types of objects,
list objects and
element objects. However, as
these objects are stored in shared memory which is managed by
psm(3),
pointers to these objects are carried as PsmAddress values. A list knows how
many elements it contains and what its first and last elements are. An element
knows what list it belongs to and the elements before and after it in its
list. An element also knows its content, which is normally the PsmAddress of
some object in shared memory.
- PsmAddress sm_list_create(PsmPartition partition)
- Create a new list object without any elements in it, within
the memory segment identified by partition. Returns the PsmAddress
of the list, or 0 on any error.
- void sm_list_unwedge(PsmPartition partition, PsmAddress
list, int interval)
- Unwedge, as necessary, the mutex semaphore protecting
shared access to the indicated list. For details, see the explanation of
the sm_SemUnwedge() function in platform(3).
- int sm_list_clear(PsmPartition partition, PsmAddress list,
SmListDeleteFn delete, void *argument);
- Empty a list. Frees each element of the list. If the
delete function is non-NULL, that function is called once for each
freed element; when called, that function is passed the PsmAddress that is
the element's data and the argument pointer passed to
sm_list_clear(). Returns 0 on success, -1 on any error.
- int sm_list_destroy(PsmPartition partition, PsmAddress
list, SmListDeleteFn delete, void *argument);
- Destroy a list. Same as sm_list_clear(), but
additionally frees the list structure itself. Returns 0 on success, -1 on
any error.
- int sm_list_user_data_set(PsmPartition partition,
PsmAddress list, PsmAddress userData);
- Set the value of a user data variable associated with the
list as a whole. This value may be used for any purpose; it is typically
used to store the PsmAddress of a shared memory block containing data
(e.g., state data) which the user wishes to associate with the list.
Returns 0 on success, -1 on any error.
- PsmAddress sm_list_user_data(PsmPartition partition,
PsmAddress list);
- Return the value of the user data variable associated with
the list as a whole, or 0 on any error.
- int sm_list_length(PsmPartition partition, PsmAddress
list);
- Return the number of elements in the list.
- PsmAddress sm_list_insert(PsmPartition partition,
PsmAddress list, PsmAddress data, SmListCompareFn compare, void
*dataBuffer);
- Create a new list element whose data value is data
and insert it into the given list. If the compare function is NULL,
the new list element is simply appended to the list; otherwise, the new
list element is inserted after the last element in the list whose data
value is "less than or equal to" the data value of the new
element (in dataBuffer) according to the collating sequence
established by compare. Returns the PsmAddress of the new element,
or 0 on any error.
- PsmAddress sm_list_insert_first(PsmPartition partition,
PsmAddress list, PsmAddress data);
- PsmAddress sm_list_insert_last(PsmPartition partition,
PsmAddress list, PsmAddress data);
- Create a new list element and insert it at the start/end of
a list. Returns the PsmAddress of the new element on success, or 0 on any
error. Disregards any established sort order in the list.
- PsmAddress sm_list_insert_before(PsmPartition partition,
PsmAddress elt, PsmAddress data);
- PsmAddress sm_list_insert_after(PsmPartition partition,
PsmAddress elt, PsmAddress data);
- Create a new list element and insert it before/after a
given element. Returns the PsmAddress of the new element on success, or 0
on any error. Disregards any established sort order in the list.
- int sm_list_delete(PsmPartition partition, PsmAddress elt,
SmListDeleteFn delete, void *argument);
- Delete an element from a list. If the delete
function is non-NULL, that function is called upon deletion of elt;
when called, that function is passed the PsmAddress that is the element's
data value and the argument pointer passed to
sm_list_delete(). Returns 0 on success, -1 on any error.
- PsmAddress sm_list_first(PsmPartition partition, PsmAddress
list);
- PsmAddress sm_list_last(PsmPartition partition, PsmAddress
list);
- Return the PsmAddress of the first/last element in
list, or 0 on any error.
- PsmAddress sm_list_next(PsmPartition partition, PsmAddress
elt);
- PsmAddress sm_list_prev(PsmPartition partition, PsmAddress
elt);
- Return the PsmAddress of the element following/preceding
elt in that element's list, or 0 on any error.
- PsmAddress sm_list_search(PsmPartition partition,
PsmAddress elt, SmListCompareFn compare, void *dataBuffer);
- Search a list for an element whose data matches the data in
dataBuffer. If the compare function is non-NULL, the list is
assumed to be sorted in the order implied by that function and the
function is automatically called once for each element of the list until
it returns a value that is greater than or equal to zero (where zero
indicates an exact match and a value greater than zero indicates that the
list contains no matching element); each time compare is called it
is passed the PsmAddress that is the element's data value and the
dataBuffer value passed to sm_list_search(). If
compare is NULL, then the entire list is searched until an element
is located whose data value is equal to ((PsmAddress) dataBuffer).
Returns the PsmAddress of the matching element if one is found, 0
otherwise.
- PsmAddress sm_list_list(PsmPartition partition, PsmAddress
elt);
- Return the PsmAddress of the list to which elt
belongs, or 0 on any error.
- PsmAddress sm_list_data(PsmPartition partition, PsmAddress
elt);
- Return the PsmAddress that is the data value for
elt, or 0 on any error.
- PsmAddress sm_list_data_set(PsmPartition partition,
PsmAddress elt, PsmAddress data);
- Set the data value for elt to data, replacing
the original value. Returns the original data value for elt, or 0
on any error. The original data value for elt may or may not have
been the address of an object in memory; even if it was, that object was
NOT deleted.
Warning: changing the data value of an element of an ordered list may ruin
the ordering of the list.
USAGE¶
A user normally creates an element and adds it to a list by doing the following:
- 1.
- obtaining a shared memory block to contain the element's
data;
- 2.
- converting the shared memory block's PsmAddress to a
character pointer;
- 3.
- using that pointer to write the data into the shared memory
block;
- 4.
- calling one of the sm_list_insert functions to
create the element structure (which will include the shared memory block's
PsmAddress) and insert it into the list.
When inserting elements or searching a list, the user may optionally provide a
compare function of the form:
int user_comp_name(PsmPartition partition, PsmAddress eltData,
void *dataBuffer);
When provided, this function is automatically called by the smlist function
being invoked; when the function is called it is passed the content of a list
element (
eltData, nominally the PsmAddress of an item in shared
memory) and an argument,
dataBuffer, which is nominally the address in
local memory of some other item in the same format. The user-supplied function
normally compares some key values of the two data items and returns 0 if they
are equal, an integer less than 0 if
eltData's key value is less than
that of
dataBuffer, and an integer greater than 0 if
eltData's
key value is greater than that of
dataBuffer. These return values will
produce a list in ascending order. If the user desires the list to be in
descending order, the function must reverse the signs of these return values.
When deleting an element or destroying a list, the user may optionally provide a
delete function of the form:
void user_delete_name(PsmPartition partition, PsmAddress eltData,
void *argData)
When provided, this function is automatically called by the smlist function
being invoked; when the function is called it is passed the content of a list
element (
eltData, nominally the PsmAddress of an item in shared
memory) and an argument,
argData, which if non-NULL is normally the
address in local memory of a data item providing context for the list element
deletion. The user-supplied function performs any application-specific cleanup
associated with deleting the element, such as freeing the element's content
data item and/or other memory associated with the element.
EXAMPLE¶
For an example of the use of smlist, see the file smlistsh.c in the utils
directory of ICI.
SEE ALSO¶
lyst(3),
platform(3),
psm(3)