Index

Package: Mutable_Lists (generic)

Description

generic
   type Element_Type is private;

   with function "="( left, right : Element_Type ) return Boolean is <>;

package Mutable_Lists is

Classes

List

type List is tagged limited private;

Primitive operations:

Append_No_Duplicate
Find_Next
Iterate_With_Quit
A List is a thread-safe mutable list backed by doubly linked list. Mutable lists may be modified during iteration, so it is possible for a thread A to add to or remove elements from the list while a thread B is iterating across the list. However, elements which are being examined by a cursor or the Iterate procedure are locked to prevent other threads from modifying or removing elements referenced by cursors. Lists only support Append and Prepend additions. While the atomic list operations provided in this package are thread safe, there is no guarantee that the list will not be modified by a different thread between calls. For example, the following may fail: if list.Is_Empty then list.Append( element ); end if; Assert( not list.Is_Empty ); The list may be modified by other threads between the calls to Is_Empty and Append.

Types

Element_Type

type Element_Type is private;

Cursor

type Cursor is limited private;
A Cursor references a location in a list. List elements referenced by cursors are locked and can only be examined via the open cursor referencing them. Any threads attempting to reference a locked list element will block until the element's cursor is closed. Note that while a List is thread safe, a Cursor is not.

A_List

type A_List is access all List'Class;

Constants & Global variables

Container_Error

Container_Error : exception;
Raised when any kind of use error occurs while using a mutable list. See the exception occurence's message for details.

Subprograms & Entries

=

function "="
( left, right: Element_Type ) return Boolean is <>;

Close

procedure Close
( position: in out Cursor );
Closes the cursor, unlocking the list element under examination.

Element

function Element
( position: Cursor ) return Element_Type;
Returns the element referenced by the cursor. An exception is raised on error.

Has_Element

function Has_Element
( position: Cursor ) return Boolean;
Returns True if the cursor is open, referencing an existing list element.

Next

procedure Next
( position: in out Cursor );
Modifies the cursor to point to the next element in the list, blocking if the next element is already being examined.

Append

procedure Append
( this: access List;
element: Element_Type );
Appends the element to the list.

Append_No_Duplicate

procedure Append_No_Duplicate
( this: access List;
element: Element_Type;
inserted: out Boolean );
Appends the element to the list unless it's already in the list. Inserted will be returned as True if the append was performed.

Clear

procedure Clear
( this: access List );
Clears the list, blocking on elements that are being examined.

Find

procedure Find
( this: access List;
element: Element_Type;
position: out Cursor );
Returns a cursor pointing to the element in the list if it is found. The procedure will block if the element is being examined. If the element is not found in the list, a null cursor will be returned.

First

procedure First
( this: access List;
position: out Cursor );
Returns a cursor pointing to the first element in the list, blocking if the first element is being examined.

Is_Empty

function Is_Empty
( this: access List ) return Boolean;
Returns True if the list has no elements.

Iterate

procedure Iterate
( this: access List;
examine: access procedure( element : Element_Type ) );
Iterates forward through the list, blocking on elements that are already being examined. Any thread can still modify the list while one thread is iterating over it, except for elements that are being examined.

Iterate_With_Quit

procedure Iterate_With_Quit
( this: access List;
examine: access procedure( element : Element_Type;
quit: in out Boolean ) );
Iterates forward through the list with the option of an early exit. Set quit to True in the examine procedure to abort iteration. See Iterate for further details.

Length

function Length
( this: access List ) return Natural;
Returns the number of elements in the list.

Prepend

procedure Prepend
( this: access List;
element: Element_Type );
Prepends an element to the list.

Remove

procedure Remove
( this: access List;
position: in out Cursor );
Removes the element pointed to by position, blocking if the element is being examined. The cursor will be closed.

Delete

procedure Delete
( this: in out A_List );
Deletes the list. If there are any open cursors, the deletion will fail without modifying the list and an exception will be raised.