ListClsEx.cpp

Go to the documentation of this file.

//==---------------------------------------------------------------------------
// DLinkListEx uses a Windows locking mechanism, so, unlike DLinkList,
// it can't be built on another platform (and hence may use the rest of uLib).
//==---------------------------------------------------------------------------

// NOTA BENE: THIS IS AN EXPERIMENTAL MODULE AND MIGHT NOT WORK AS EXPECTED...

#include <uLib/ListEx.h>
#include <uLib/Debug.h>

//==---------------------------------------------------------------------------
// DLinkListEx - Mutually exclusive access
//==---------------------------------------------------------------------------


DLinkListEx::DLinkListEx( DWORD SpinCount )
: DLinkList()
{
    SetLastError( 0 ); // Allow caller to examine success of c'tor, since...
    InitializeCriticalSectionAndSpinCount( &_csect, SpinCount ); //... SetLastError
}

DLinkListEx::DLinkListEx( PLIST_ENTRY ListHead, DWORD SpinCount ) // Pick up a plain DDK list.
: DLinkList()
{
    SafeRemove = true;
    SetLastError( 0 ); // Dito...
    InitializeCriticalSectionAndSpinCount( &_csect, SpinCount ); //...
    if (Lock( true ))
    {
        _grabList( ListHead );
        Unlock();
    }
}

DLinkListEx::~DLinkListEx()
{
    TRACE_IF( Count > 0, DP_WARNING, _F("Deleting non-empty list. Count=%lu\n"), Count );
    DeleteCriticalSection( &_csect );
}

bool DLinkListEx::Lock( bool Wait )
{
    bool ok;
    if (!Wait)
    {
        ok = bool_cast( TryEnterCriticalSection( &_csect ));
        if (!ok) SetLastError( ERROR_LOCK_FAILED );
    }
    else
    {
        // MSDN: "EnterCriticalSection can raise EXCEPTION_POSSIBLE_DEADLOCK
        // if a wait operation on the critical section times out. Do not handle
        // a possible deadlock exception; instead, debug the application."

        EnterCriticalSection( &_csect ); // May except...
        ok = true;
    }
    return ok;
}

void DLinkListEx::Unlock()
{
    LeaveCriticalSection( &_csect );
}

DWORD DLinkListEx::SetLockSpinCount( DWORD SpinCount )
{
    return SetCriticalSectionSpinCount( &_csect, SpinCount );
}

//==---------------------------------------------------------------------------
// Content transfer: Wait for lock
//==---------------------------------------------------------------------------

UINT DLinkListEx::ExportToListHead( PLIST_ENTRY ListHead )
{
    UINT count = 0;
    if (Lock( true ))
    {
        count = DLinkList::ExportToListHead( ListHead );
        Unlock();
    }
    return count;
}

UINT DLinkListEx::ImportFromListHead( PLIST_ENTRY ListHead, PLIST_ENTRY* ppFirst )
{
    UINT count = 0;
    if (Lock( true ))
    {
        count = DLinkList::ImportFromListHead( ListHead, ppFirst );
        Unlock();
    }
    return count;
}

UINT DLinkListEx::ExportToHeadlessList( PLIST_ENTRY* Target )
{
    UINT count = 0;
    if (Lock( true ))
    {
        count = DLinkList::ExportToHeadlessList( Target );
        Unlock();
    }
    return count;
}

UINT DLinkListEx::ImportHeadlessList( PLIST_ENTRY Circular, PLIST_ENTRY* ppFirst )
{
    UINT count = 0;
    if (Lock( true ))
    {
        count = DLinkList::ImportHeadlessList( Circular, ppFirst );
        Unlock();
    }
    return count;
}

//==---------------------------------------------------------------------------
// Content change: Wait for lock
//==---------------------------------------------------------------------------

PLIST_ENTRY DLinkListEx::Append( PLIST_ENTRY Entry )
{
    if (!Lock( true )) Entry = NULL;
    else
    {
        Entry = DLinkList::Append( Entry );
        Unlock();
    }
    return Entry;
}

PLIST_ENTRY DLinkListEx::Prepend( PLIST_ENTRY Entry )
{
    if (!Lock( true )) Entry = NULL;
    else
    {
        Entry = DLinkList::Prepend( Entry );
        Unlock();
    }
    return Entry;
}

UINT DLinkListEx::AppendList( PLIST_ENTRY ListToAppend, PLIST_ENTRY* ppFirst )
{
    // ListToAppend is the /head/ of the list to append.

    UINT nrAdded = 0;
    if (Lock( true ))
    {
        nrAdded = DLinkList::AppendList( ListToAppend, ppFirst );
        Unlock();
    }
    return nrAdded;
}

UINT DLinkListEx::AppendList( PDLinkList ListToAppend, PLIST_ENTRY* ppFirst ) // preliminary
{
    UINT nrAdded = DLinkListEx::AppendList( (PLIST_ENTRY)ListToAppend, ppFirst );
    if (nrAdded) ListToAppend->Count = 0; // If success, ListToAppend is cleared.
    return nrAdded;
}

PLIST_ENTRY DLinkListEx::RemoveEntry( PLIST_ENTRY Entry ) // Return Entry if removed, else NULL
{
    if (!Lock( true )) Entry = NULL;
    else
    {
        Entry = DLinkList::RemoveEntry( Entry );
        Unlock();
    }
    return Entry;
}

void DLinkListEx::RemoveAll( PDListFunc ItemAction, void* UserData )
{
    if (Lock( true ))
    {
        // Note: Because RemoveEntry is not virtual, the inherited RemoveAll will
        // call it's own RemoveEntry, not our Ex version, so we don't have to be
        // concerned about inefficient reaquiring of an already owned lock.

        DLinkList::RemoveAll( ItemAction, UserData );
        Unlock();
    }
}

//==---------------------------------------------------------------------------
// Sort: Wait for lock
//==---------------------------------------------------------------------------

void DLinkListEx::QuickSort( PDListComp Compare, void* Context )
{
    if (Lock( true ))
    {
        DLinkList::QuickSort( Compare, Context );
        Unlock();
    }
}

//==---------------------------------------------------------------------------
// Enumeration: Lock if able, else abort
//==---------------------------------------------------------------------------

PLIST_ENTRY DLinkListEx::FirstThat( PDListFunc Match, void* UserData )
{
    PLIST_ENTRY item = NULL;
    bool locked = Lock();
    TRACE( DP_VERBOSE, _F("Locked = %u\n"), locked );
    if (locked)
    {
        item = DLinkList::FirstThat( Match, UserData );
        Unlock();
    }
    return item;
}

PLIST_ENTRY DLinkListEx::LastThat( PDListFunc Match, void* UserData )
{
    PLIST_ENTRY item = NULL;
    bool locked = Lock();
    TRACE( DP_VERBOSE, _F("Locked = %u\n"), locked );
    if (locked)
    {
        item = DLinkList::LastThat( Match, UserData );
        Unlock();
    }
    return item;
}

bool DLinkListEx::ForEach( PDListFunc Action, void* UserData )
{
    bool complete = false;
    bool locked = Lock();
    TRACE( DP_VERBOSE, _F("Locked = %u\n"), locked );
    if (locked)
    {
        complete = DLinkList::ForEach( Action, UserData );
        Unlock();
    }
    return complete;
}

// EOF