SysLink API Reference
2.21.03.11
|
Multiple processor shared memory list.
===========================================================================
ListMP is a doubly linked-list based module designed to be used in a multi-processor environment. It provides a way for multiple processors to create, access, and manipulate the same link list in shared memory.
The ListMP module uses a NameServer instance to store information about an instance during create. Each ListMP instance is created by specifying a name and region id. The name supplied must be unique for all ListMP instances in the system.
ListMP_create() is used to create an instance of a ListMP. Shared memory is modified during create. Once created, an instance may be opened by calling ListMP_open(). Open does not modify any shared memory. Open() should be called only when global interrupts are enabled.
To use a ListMP instance, a ListMP_Elem must be embedded as the very first element of a structure. ListMP does not provide cache coherency for the buffer put onto the link list. ListMP only provides cache coherency for the ListMP_Elem fields. The buffer should be written back before being placed on a ListMP, if cache coherency is required.
The ListMP header should be included in an application as follows:
============================================================================
Go to the source code of this file.
Data Structures | |
struct | ListMP_Elem |
Structure defining a ListMP element. More... | |
struct | ListMP_Params |
Structure defining parameter structure for ListMP_create(). More... |
Macros | |
#define | ListMP_S_BUSY 2 |
The resource is still in use. | |
#define | ListMP_S_ALREADYSETUP 1 |
The module has been already setup. | |
#define | ListMP_S_SUCCESS 0 |
Operation is successful. | |
#define | ListMP_E_FAIL -1 |
Generic failure. | |
#define | ListMP_E_INVALIDARG -2 |
Argument passed to function is invalid. | |
#define | ListMP_E_MEMORY -3 |
Operation resulted in memory failure. | |
#define | ListMP_E_ALREADYEXISTS -4 |
The specified entity already exists. | |
#define | ListMP_E_NOTFOUND -5 |
Unable to find the specified entity. | |
#define | ListMP_E_TIMEOUT -6 |
Operation timed out. | |
#define | ListMP_E_INVALIDSTATE -7 |
Module is not initialized. | |
#define | ListMP_E_OSFAILURE -8 |
A failure occurred in an OS-specific call. | |
#define | ListMP_E_RESOURCE -9 |
Specified resource is not available. | |
#define | ListMP_E_RESTART -10 |
Operation was interrupted. Please restart the operation. |
Typedefs | |
typedef struct ListMP_Object * | ListMP_Handle |
ListMP_Handle type. | |
typedef struct ListMP_Elem | ListMP_Elem |
Structure defining a ListMP element. | |
typedef struct ListMP_Params | ListMP_Params |
Structure defining parameter structure for ListMP_create(). |
Functions | |
Void | ListMP_Params_init (ListMP_Params *params) |
Initializes ListMP parameters. | |
ListMP_Handle | ListMP_create (const ListMP_Params *params) |
Creates and initializes ListMP module. | |
Int | ListMP_close (ListMP_Handle *handlePtr) |
Close an opened ListMP instance. | |
Int | ListMP_delete (ListMP_Handle *handlePtr) |
Deletes a ListMP instance. | |
Int | ListMP_open (String name, ListMP_Handle *handlePtr) |
Open a created ListMP instance. | |
Bool | ListMP_empty (ListMP_Handle handle) |
Determines if a ListMP instance is empty. | |
GateMP_Handle | ListMP_getGate (ListMP_Handle handle) |
Retrieves the GateMP handle associated with the ListMP instance. | |
Ptr | ListMP_getHead (ListMP_Handle handle) |
Get an element from front of a ListMP instance. | |
Ptr | ListMP_getTail (ListMP_Handle handle) |
Get an element from back of a ListMP instance. | |
Int | ListMP_insert (ListMP_Handle handle, ListMP_Elem *newElem, ListMP_Elem *curElem) |
Insert an element into a ListMP instance. | |
Ptr | ListMP_next (ListMP_Handle handle, ListMP_Elem *elem) |
Return the next element in a ListMP instance (non-atomic) | |
Ptr | ListMP_prev (ListMP_Handle handle, ListMP_Elem *elem) |
Return the previous element in ListMP instance (non-atomic) | |
Int | ListMP_putHead (ListMP_Handle handle, ListMP_Elem *elem) |
Put an element at head of a ListMP instance. | |
Int | ListMP_putTail (ListMP_Handle handle, ListMP_Elem *elem) |
Put an element at back of a ListMP instance. | |
Int | ListMP_remove (ListMP_Handle handle, ListMP_Elem *elem) |
Remove an element from a ListMP instance. |
#define ListMP_S_BUSY 2 |
The resource is still in use.
#define ListMP_S_ALREADYSETUP 1 |
The module has been already setup.
#define ListMP_S_SUCCESS 0 |
Operation is successful.
#define ListMP_E_FAIL -1 |
Generic failure.
#define ListMP_E_INVALIDARG -2 |
Argument passed to function is invalid.
#define ListMP_E_MEMORY -3 |
Operation resulted in memory failure.
#define ListMP_E_ALREADYEXISTS -4 |
The specified entity already exists.
#define ListMP_E_NOTFOUND -5 |
Unable to find the specified entity.
#define ListMP_E_TIMEOUT -6 |
Operation timed out.
#define ListMP_E_INVALIDSTATE -7 |
Module is not initialized.
#define ListMP_E_OSFAILURE -8 |
A failure occurred in an OS-specific call.
#define ListMP_E_RESOURCE -9 |
Specified resource is not available.
#define ListMP_E_RESTART -10 |
Operation was interrupted. Please restart the operation.
typedef struct ListMP_Object* ListMP_Handle |
ListMP_Handle type.
typedef struct ListMP_Elem ListMP_Elem |
Structure defining a ListMP element.
typedef struct ListMP_Params ListMP_Params |
Structure defining parameter structure for ListMP_create().
Void ListMP_Params_init | ( | ListMP_Params * | params | ) |
Initializes ListMP parameters.
params | Instance param structure. |
ListMP_Handle ListMP_create | ( | const ListMP_Params * | params | ) |
Creates and initializes ListMP module.
params | Instance param structure. |
Int ListMP_close | ( | ListMP_Handle * | handlePtr | ) |
Close an opened ListMP instance.
Closing an instance will free local memory consumed by the opened instance. Instances that are opened should be closed before the instance is deleted. If using NameServer, the instance name will be removed from the NameServer instance.
handlePtr | Pointer to a ListMP instance |
Int ListMP_delete | ( | ListMP_Handle * | handlePtr | ) |
Deletes a ListMP instance.
handlePtr | Pointer to ListMP instance |
Int ListMP_open | ( | String | name, |
ListMP_Handle * | handlePtr | ||
) |
Open a created ListMP instance.
An open can be performed on a previously created instance. Open is used to gain access to the same ListMP instance. Generally an instance is created on one processor and opened on other processors but it can be opened on the same processor too. Open returns a ListMP instance handle like create, but it does not initialize any shared memory.
The open call searches the local ListMP NameServer table first for a matching name. If no local match is found, it will search all remote ListMP NameServer tables for a matching name.
A status value of ListMP_S_SUCCESS is returned if a matching ListMP instance is found. A ListMP_E_FAIL is returned if no matching instance is found. Generally this means the ListMP instance has not yet been created. A more specific status error is returned if an error was raised.
Call close() when the opened instance is no longer needed.
name | Name of created ListMP instance |
handlePtr | pointer to the handle if a handle was found. |
Bool ListMP_empty | ( | ListMP_Handle | handle | ) |
Determines if a ListMP instance is empty.
handle | a ListMP handle. |
GateMP_Handle ListMP_getGate | ( | ListMP_Handle | handle | ) |
Retrieves the GateMP handle associated with the ListMP instance.
handle | a ListMP handle. |
Ptr ListMP_getHead | ( | ListMP_Handle | handle | ) |
Get an element from front of a ListMP instance.
Atomically removes the element from the front of a ListMP instance and returns a pointer to it. Uses ListMP_Params::gate for critical region management.
handle | a ListMP handle. |
Ptr ListMP_getTail | ( | ListMP_Handle | handle | ) |
Get an element from back of a ListMP instance.
Atomically removes the element from the back of a ListMP instance and returns a pointer to it. Uses ListMP_Params::gate for critical region management.
handle | a ListMP handle. |
Int ListMP_insert | ( | ListMP_Handle | handle, |
ListMP_Elem * | newElem, | ||
ListMP_Elem * | curElem | ||
) |
Insert an element into a ListMP instance.
Atomically inserts `newElem` in the instance in front of `curElem`. To place an element at the back of a ListMP instance, use ListMP_putTail. To place an element at the front of a ListMP instance, use ListMP_putHead.
The following code shows an example.
handle | a ListMP handle. |
newElem | new element to insert into the ListMP. |
curElem | current element in the ListMP. |
Ptr ListMP_next | ( | ListMP_Handle | handle, |
ListMP_Elem * | elem | ||
) |
Return the next element in a ListMP instance (non-atomic)
Is useful in searching a ListMP instance. It does not remove any items from the ListMP instance. The caller should protect the ListMP instance from being changed while using this call since it is non-atomic.
To look at the first `elem` on the ListMP, use NULL as the `elem` argument.
The following code shows an example. The scanning of a ListMP instance should be protected against other threads that modify the ListMP.
handle | a ListMP handle. |
elem | element in ListMP or NULL to start at the head |
Ptr ListMP_prev | ( | ListMP_Handle | handle, |
ListMP_Elem * | elem | ||
) |
Return the previous element in ListMP instance (non-atomic)
Useful in searching a ListMP instance in reverse order. It does not remove any items from the ListMP instance. The caller should protect the ListMP instance from being changed while using this call since it is non-atomic.
To look at the last `elem` on the ListMP instance, use NULL as the `elem` argument.
The following code shows an example. The scanning of a ListMP instance should be protected against other threads that modify the instance.
handle | a ListMP handle. |
elem | element in ListMP or NULL to start at the end |
Int ListMP_putHead | ( | ListMP_Handle | handle, |
ListMP_Elem * | elem | ||
) |
Put an element at head of a ListMP instance.
Atomically places the element at the front of a ListMP instance. Uses ListMP_Params::gate for critical region management.
handle | a ListMP handle |
elem | pointer to new ListMP element |
Int ListMP_putTail | ( | ListMP_Handle | handle, |
ListMP_Elem * | elem | ||
) |
Put an element at back of a ListMP instance.
Atomically places the element at the back of a ListMP instance. Uses ListMP_Params::gate for critical region management.
handle | a ListMP handle |
elem | pointer to new ListMP element |
Int ListMP_remove | ( | ListMP_Handle | handle, |
ListMP_Elem * | elem | ||
) |
Remove an element from a ListMP instance.
Atomically removes an element from a ListMP.
The `elem` parameter is a pointer to an existing element to be removed from a ListMP instance.
handle | a ListMP handle |
elem | element in ListMP |