mplist.h File Reference

#include <dsplink.h>
#include <mplistdefs.h>

Include dependency graph for gpp/inc/mplist.h:

Go to the source code of this file.

Functions
DLLEXPORT DSP_STATUS	MPLIST_create (IN ProcessorId procId, IN Char8 *name, IN MPLIST_List *mplistObj, IN MPLIST_Attrs *attrs)
	Allocates and initializes a doubly linked circular list in shared memory. The memory for the object may or may not be provided by the user. Uses POOl api to allocate a list object. The list object contains a MPCS object and a single element and initializes that element to indicate that it is the "end of the list" (i.e., the list is empty). An entry is added in the shared memory control structure for the list.
DLLEXPORT DSP_STATUS	MPLIST_delete (IN ProcessorId procId, IN Char8 *name)
	Removes a list by freeing its control structure's memory space. Must ONLY be used for empty lists, because it does not delete the list elements. Calling this function on a non-empty list will cause a memory leak.
DLLEXPORT DSP_STATUS	MPLIST_open (IN ProcessorId procId, IN Char8 *name, OUT MPLIST_Handle *mplistHandle)
	This function opens an MPLIST object specified by its name and gets a handle to the object. Every process that needs to use the MPLIST object must get a handle to the object by calling this API.
DLLEXPORT DSP_STATUS	MPLIST_close (IN MPLIST_Handle mplistHandle)
	This function closes an MPLIST instance.
DLLEXPORT Bool	MPLIST_isEmpty (IN MPLIST_Handle mplistHandle)
	Check for an empty list.
DLLEXPORT DSP_STATUS	MPLIST_insertBefore (IN MPLIST_Handle mplistHandle, IN MPLIST_Elem insertElement, IN MPLIST_Elem existingElement)
	Inserts the element before the existing element.
DLLEXPORT DSP_STATUS	MPLIST_putTail (IN MPLIST_Handle mplistHandle, IN MPLIST_Elem element)
	Adds the specified element to the tail of the list.
DLLEXPORT DSP_STATUS	MPLIST_removeElement (IN MPLIST_Handle mplistHandle, IN MPLIST_Elem element)
	Removes (unlinks) the given element from the list, if the list is not empty. Does not free the list element.
DLLEXPORT DSP_STATUS	MPLIST_first (IN MPLIST_Handle mplistHandle, OUT MPLIST_Elem *element)
	Returns a pointer to the first element of the list, or NULL if the list is empty.
DLLEXPORT DSP_STATUS	MPLIST_next (IN MPLIST_Handle mplistHandle, IN MPLIST_Elem currentElement, OUT MPLIST_Elem *nextElement)
	Returns a pointer to the next element of the list, or NULL if the next element is the head of the list or the list is empty.
DLLEXPORT DSP_STATUS	MPLIST_getHead (IN MPLIST_Handle mplistHandle, OUT MPLIST_Elem *element)
	Pops the head off the list and returns a pointer to it. If the list is empty, returns NULL.

---

Function Documentation

DLLEXPORT DSP_STATUS MPLIST_create	(	IN ProcessorId	procId,
		IN Char8 *	name,
		IN MPLIST_List *	mplistObj,
		IN MPLIST_Attrs *	attrs
	)

Allocates and initializes a doubly linked circular list in shared memory. The memory for the object may or may not be provided by the user. Uses POOl api to allocate a list object. The list object contains a MPCS object and a single element and initializes that element to indicate that it is the "end of the list" (i.e., the list is empty). An entry is added in the shared memory control structure for the list.

============================================================================

Function:

MPLIST_create

Parameters:

procId	Processor id of the processor making this create call.
mplistObj	Pointer to the shared MPLIST object. If memory for the MPLIST object is provided by the user, the MPLIST object handle is not NULL. Otherwise, if the memory is to be allocated by the MPLIST component, the MPLIST object handle can be specified as NULL.
name	Name of the list to be created.
attrs	Attributes of the list to be created.

Returns:

DSP_SOK Operation successfully completed. DSP_EINVALIDARG Invalid arguments. DSP_EMEMORY Operation failed due to a memory error. DSP_EALREADYEXISTS The specified MPLIST name is already in use. DSP_ERESOURCE All MPLIST entries are currently in use. DSP_EACCESSDENIED The MPLIST component has not been initialized. DSP_ENOTFOUND Information about specified POOL buffer was not available. DSP_EFAIL General failure.

Precondition:

Processor id must be valid. MPLIST name must be valid. MPLIST creation attributes must be a valid. PROC_attach has been successful. POOL has been configured according to application specification.

Postcondition:

None

See also:

MPLIST_delete ============================================================================

DLLEXPORT DSP_STATUS MPLIST_delete	(	IN ProcessorId	procId,
		IN Char8 *	name
	)

Removes a list by freeing its control structure's memory space. Must ONLY be used for empty lists, because it does not delete the list elements. Calling this function on a non-empty list will cause a memory leak.

============================================================================

Function:

MPLIST_delete

Parameters:

procId	Processor id of the processor making this delete call.
name	Name of the list to be deleted.

Returns:

DSP_SOK Operation successfully completed. DSP_EINVALIDARG Invalid arguments. DSP_EACCESSDENIED The MPLIST component has not been initialized. DSP_ENOTFOUND The MPLIST to be deleted is not present. Information about specified POOL buffer was not available. DSP_EFAIL General Failure.

Precondition:

Processor Id must be valid. MPLIST name must be valid. All MPLIST operations on that MP_LIST are complete.

Postcondition:

None

See also:

MPLIST_create ============================================================================

DLLEXPORT DSP_STATUS MPLIST_open	(	IN ProcessorId	procId,
		IN Char8 *	name,
		OUT MPLIST_Handle *	mplistHandle
	)

This function opens an MPLIST object specified by its name and gets a handle to the object. Every process that needs to use the MPLIST object must get a handle to the object by calling this API.

============================================================================

Function:

MPLIST_open

Parameters:

procId	Processor id of the processor making the open call.
name	Name of the list to be opened.
mplistHandle	Handle of list which has been opened.

Returns:

DSP_SOK Operation successfully completed. DSP_EINVALIDARG Invalid arguments. DSP_EFAIL General Failure. DSP_EACCESSDENIED The MPLIST component has not been initialized. DSP_ENOTFOUND The MPLIST to be deleted is not present. Information about specified POOL buffer was not available. DSP_EACCESSDENIED The MPLIST component has not been initialized.

Precondition:

mplistHandle must be a valid pointer. name must be a valid pointer. MPLIST_create has been successful.

Postcondition:

None

See also:

MPLIST_close ============================================================================

DLLEXPORT DSP_STATUS MPLIST_close

(

IN MPLIST_Handle

mplistHandle )

This function closes an MPLIST instance.

============================================================================

Function:

MPLIST_close

Parameters:

mplistHandle

Handle for list operations.

Returns:

DSP_SOK Operation successfully completed. DSP_SFREE Resource has been freed successfully. DSP_EINVALIDARG Invalid arguments. DSP_EACCESSDENIED The MPLIST component has not been initialized. DSP_EFAIL General Failure.

Precondition:

mplistHandle must be a valid pointer. All MPLIST operations are successful.

Postcondition:

None

See also:

MPLIST_open

Modifies:

None ============================================================================

DLLEXPORT Bool MPLIST_isEmpty

(

IN MPLIST_Handle

mplistHandle )

Check for an empty list.

============================================================================

Function:

MPLIST_isEmpty

Parameters:

mplistHandle

Handle for list operations.

Returns:

TRUE List is empty. FALSE List is not empty.

Precondition:

mplistHandle must be a valid pointer. MPLIST_create has been successful.

Postcondition:

None

See also:

None ============================================================================

DLLEXPORT DSP_STATUS MPLIST_insertBefore	(	IN MPLIST_Handle	mplistHandle,
		IN MPLIST_Elem	insertElement,
		IN MPLIST_Elem	existingElement
	)

Inserts the element before the existing element.

============================================================================

Function:

MPLIST_insertBefore

Parameters:

mplistHandle	Handle for list operations.
insertElement	Pointer to element in list to insert.
existingElement	Pointer to existing list element.

Returns:

DSP_SOK Operation successfully completed. DSP_EINVALIDARG Invalid arguments. DSP_ENOTFOUND Information about specified POOL buffer was not available. DSP_EFAIL General Failure.

Precondition:

mplistHandle must be a valid pointer. insertElement must be a valid pointer. existingElement must be a valid pointer. MPLIST_open has been successful.

Postcondition:

None

See also:

MPLIST_create, MPLIST_putTail ============================================================================

DLLEXPORT DSP_STATUS MPLIST_putTail	(	IN MPLIST_Handle	mplistHandle,
		IN MPLIST_Elem	element
	)

Adds the specified element to the tail of the list.

============================================================================

Function:

MPLIST_putTail

Parameters:

mplistHandle	Handle for list operations.
element	Pointer to list element to be added.

Returns:

DSP_SOK Operation successfully completed. DSP_EINVALIDARG Invalid arguments. DSP_ENOTFOUND Information about specified POOL buffer was not available. DSP_EFAIL General Failure.

Precondition:

mplistHandle must be a valid pointer. element must be a valid pointer. MPLIST_open has been successful.

Postcondition:

None

See also:

MPLIST_insertBefore ============================================================================

DLLEXPORT DSP_STATUS MPLIST_removeElement	(	IN MPLIST_Handle	mplistHandle,
		IN MPLIST_Elem	element
	)

Removes (unlinks) the given element from the list, if the list is not empty. Does not free the list element.

============================================================================

Function:

MPLIST_removeElement

Parameters:

mplistHandle	Handle for list operations.
element	Pointer to element in list to remove.

Returns:

DSP_SOK Operation successfully completed. DSP_EINVALIDARG Invalid arguments. DSP_EFAIL General Failure.

Precondition:

mplistHandle must be a valid pointer. element be a valid pointer. MPLIST_open has been successful.

Postcondition:

None

See also:

MPLIST_insertBefore, MPLIST_create, MPLIST_putTail ============================================================================

DLLEXPORT DSP_STATUS MPLIST_first	(	IN MPLIST_Handle	mplistHandle,
		OUT MPLIST_Elem *	element
	)

Returns a pointer to the first element of the list, or NULL if the list is empty.

============================================================================

Function:

MPLIST_first

Parameters:

mplistHandle	Handle for list operations.
element	OUT parameter for holding the first element.

Returns:

DSP_SOK Operation successfully completed. DSP_EINVALIDARG Invalid arguments. DSP_EFAIL General Failure.

Precondition:

mplistHandle must be a valid pointer. element be a valid pointer. MPLIST_open has been successful.

Postcondition:

None

See also:

MPLIST_create, MPLIST_puttail, MPLIST_insertbefore ============================================================================

DLLEXPORT DSP_STATUS MPLIST_next	(	IN MPLIST_Handle	mplistHandle,
		IN MPLIST_Elem	currentElement,
		OUT MPLIST_Elem *	nextElement
	)

Returns a pointer to the next element of the list, or NULL if the next element is the head of the list or the list is empty.

============================================================================

Function:

MPLIST_next

Parameters:

mplistHandle	Handle for list operations.
currentElement	Pointer to element in list to remove.
nextElement	OUT parameter to hold the next element.

Returns:

DSP_SOK Operation successfully completed. DSP_EINVALIDARG Invalid arguments. DSP_EFAIL General Failure.

Precondition:

mplistHandle must be a valid pointer. currentElement be a valid pointer. nextElement be a valid pointer. MPLIST_open has been successful.

Postcondition:

None

See also:

MPLIST_insertBefore, MPLIST_putTail ============================================================================

DLLEXPORT DSP_STATUS MPLIST_getHead	(	IN MPLIST_Handle	mplistHandle,
		OUT MPLIST_Elem *	element
	)

Pops the head off the list and returns a pointer to it. If the list is empty, returns NULL.

============================================================================

Function:

MPLIST_getHead

Parameters:

mplistHandle	Handle for list operations.
element	OUT Parameter to hold the head element.

Returns:

DSP_SOK Operation successfully completed. DSP_EINVALIDARG Invalid arguments. DSP_ENOTFOUND Information about specified POOL buffer was not available. DSP_EFAIL General Failure.

Precondition:

mplistHandle must be a valid pointer. element be a valid pointer. MPLIST_open has been successful.

Postcondition:

None

See also:

MPLIST_puttail, MPLIST_insertbefore ============================================================================