PlatformDxe/Observable/Observable.c

/*++
  This file contains 'Framework Code' and is licensed as such
  under the terms of your license agreement with Intel or your
  vendor.  This file may not be modified, except as allowed by
  additional terms of your license agreement.
--*/
/*++

Copyright (c)  2010  - 2014, Intel Corporation. All rights reserved

  This program and the accompanying materials are licensed and made available under
  the terms and conditions of the BSD License that accompanies this distribution.
  The full text of the license may be found at
  http://opensource.org/licenses/bsd-license.php.

  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.


Module Name:

  Observable.c

Abstract:

  The following contains all of the implementation for the Observable protocol. The
  protocol uses the observer design pattern to provide a way to publish events and
  to subscribe to those events so that a callback will be performed at the time of
  the event. The observables and subscribers are maintained by the static tree,
  mObservableDb. The difference between this protocol and the existing event protocol
  that exists within the EFI framework is that this protocol allows for parameters
  to be passed to the subscribed callbacks that can contain up to date context.

--*/

#include "Observable.h"

static OBS_TREE*                mObservableDb = NULL;
static EFI_HANDLE               mObservableHandle = NULL;
static OBS_OBSERVABLE_PROTOCOL  mObservable = {
  AddObservable,
  RemoveObservable,
  Subscribe,
  Unsubscribe,
  Publish,
  RemoveAllObservables
};

/** Install observable protocol.
 *
 * Install interface and initialize the observable protocol.
 *
 * @param   VOID          No parameters.
 *
 * @return  EFI_SUCCESS   Successfully installed and initialized the protocol.
 **/
EFI_STATUS
InitializeObservableProtocol(
  VOID
  )
{
  EFI_STATUS  Status;

  //
  // Install protocol.
  //
  Status = gBS->InstallProtocolInterface (
                  &mObservableHandle,
                  &gObservableProtocolGuid,
                  EFI_NATIVE_INTERFACE,
                  &mObservable
                  );

  return Status;
}

/** Deletes a subscriber
 *
 * This function removes the subscriber pointed to by Head.
 *
 * @param   OBS_TREE*     Head    Points to the current subscriber.
 *
 * @return  OBS_TREE*     Returns the tree after successfully removing the subscriber.
 **/
OBS_LEAF*
DeleteSubscriber(
  OBS_LEAF* Head
  )
{
  OBS_LEAF* Temp;

  if (Head) {
    Temp = Head;
    Head = Head->Next;
    gBS->FreePool(Temp);
  }

  return Head;
}

/** Finds and deletes all subscribers
 *
 * This function iterates recursively through the existing subscribers and delets them all.
 *
 * @param   OBS_TREE*     Head    Points to the current subscriber.
 *
 * @return  OBS_TREE*     Returns the tree after successfully removing the subscribers.
 **/
OBS_LEAF*
DeleteAllSubscribers(
  OBS_LEAF* Head
  )
{
  if (Head) {
    if (Head->Next) {
      //
      // We aren't at the end of the list yet.
      //
      Head->Next = DeleteAllSubscribers(Head->Next);
    }

    //
    // At the end, so delete the subscriber.
    //
    Head = DeleteSubscriber(Head);
  }

  return Head;
}

/** Deletes an observable
 *
 * This function removes the observable pointed to by Head.
 *
 * @param   OBS_TREE*     Head    Points to the current observable.
 *
 * @return  OBS_TREE*     Returns the tree after successfully removing the observable.
 **/
OBS_TREE*
DeleteObservable(
  OBS_TREE* Head
  )
{
  OBS_TREE* Temp;

  if (Head) {
    Temp = Head;
    Head = Head->Next;
    gBS->FreePool(Temp);
  }

  return Head;
}

/** Finds and deletes all observables
 *
 * This function iterates recursively through the existing observables database and, starting with
 * the last most observable, deletes all of its subscribers, then deletes the observable itself.
 *
 * @param   OBS_TREE*     Head    Points to the current observable.
 *
 * @return  OBS_TREE*     Returns the tree after successfully removing the observables.
 **/
OBS_TREE*
DeleteAllObservables(
  OBS_TREE* Head
  )
{
  if (Head) {
    if (Head->Next) {
      //
      // We aren't at the end of the list yet.
      //
      Head->Next = DeleteAllObservables(Head->Next);
    }

    //
    // This is the end of the list of observables.
    //
    Head->Leaf = DeleteAllSubscribers(Head->Leaf);

    //
    // Subscribers are deleted, so now delete the observable.
    //
    Head = DeleteObservable(Head);
  }

  return Head;
}

/** Finds and deletes observable
 *
 * This function iterates recursively through the existing observable database in order to find the one
 * specified by ReferenceGuid so that it can be deleted. If the requested observable is found, before it
 * is deleted, all of the subscribers that are listening to this observable are deleted.
 *
 * @param   OBS_TREE*     Head              Points to the current observable.
 *          EFI_GUID      ReferenceGuid     Corresponds to the observable that we're looking for.
 *
 * @return  OBS_TREE*     Returns the tree after successfully removing (or not finding) the observable.
 **/
OBS_TREE*
FindAndDeleteObservable(
  OBS_TREE* Head,
  EFI_GUID  ReferenceGuid
  )
{
  if (Head) {
    if (CompareMem(&(Head->ObservableGuid), &ReferenceGuid, sizeof(ReferenceGuid)) == 0) {
      //
      // We found the observable. Delete all of it's subscribers, first.
      //
      Head->Leaf = DeleteAllSubscribers(Head->Leaf);
      //
      // Now we can safely remove the observable.
      //
      Head = DeleteObservable(Head);
    } else {
      //
      // Not found. Keep searching.
      //
      Head->Next = FindAndDeleteObservable(Head->Next, ReferenceGuid);
    }
  }

  return Head;
}

/** Finds and deletes subscriber
 *
 * This function iterates recursively through the existing subscribers that are listening to the
 * observable that was found when this function was called.
 *
 * @param   OBS_TREE*     Head              Points to the current subscriber.
 *          OBS_CALLBACK  CallbackInterface This is the subscriber that is requested be removed.
 *
 * @return  OBS_TREE*     Returns the tree after successfully removing (or not finding) the subscriber.
 **/
OBS_LEAF*
_FindAndDeleteSubscriber(
  OBS_LEAF*     Head,
  OBS_CALLBACK  CallbackInterface
  )
{
  if (Head) {
    if (Head->Observer == CallbackInterface) {
      //
      // Found it. Now let's delete it.
      //
      Head = DeleteSubscriber(Head);
    } else {
      //
      // Not found. Keep searching.
      //
      Head->Next = _FindAndDeleteSubscriber(Head->Next, CallbackInterface);
    }
  }

  return Head;
}

/** Finds and deletes subscriber
 *
 * This function iterates recursively through the existing observables database until it either finds
 * a matching guid or reaches the end of the list. After finding a match, it calls a helper function,
 * _FindAndDeleteSubscriber. At this point, all responsibility for finding and deleting the subscriber
 * lies on the helper function.
 *
 * @param   OBS_TREE*     Head              Points to the current observable.
 *          EFI_GUID      ReferenceGuid     Corresponds to the observable that we're looking for.
 *          OBS_CALLBACK  CallbackInterface This is the subscriber that is requested be removed.
 *
 * @return  OBS_TREE*     Returns the tree after successfully removing (or not finding) the subscriber.
 **/
OBS_TREE*
FindAndDeleteSubscriber(
  IN  OUT OBS_TREE*     Head,
  IN      EFI_GUID      ReferenceGuid,
  IN      OBS_CALLBACK  CallbackInterface
  )
{
  if (Head) {
    if (CompareMem(&(Head->ObservableGuid), &ReferenceGuid, sizeof(ReferenceGuid)) == 0) {
      //
      // We found the observer that matches ReferenceGuid. Find and delete the subscriber that is
      // listening to it.
      //
      Head->Leaf = _FindAndDeleteSubscriber(Head->Leaf, CallbackInterface);
    } else {
      //
      // Not found. Keep searching.
      //
      Head->Next = FindAndDeleteSubscriber(Head->Next, ReferenceGuid, CallbackInterface);
    }
  }

  return Head;
}

/** Remove all observables.
 *
 * Remove all observable guids and all interfaces subscribed to them.
 *
 * @param   VOID          No parameters.
 *
 * @return  EFI_SUCCESS   Successfully removed all observables and subscribed interfaces.
 **/
EFI_STATUS
EFIAPI
RemoveAllObservables(
  VOID
  )
{
  mObservableDb = DeleteAllObservables(mObservableDb);

  return EFI_SUCCESS;
}

/** Subscribe an interface with an observable guid.
 *
 * Use this to register a callback function with a guid. The function provided by CallbackInterface will be executed
 * whenever the appropriate observable instance specified by ReferenceGuid calls Publish.
 *
 * @param   EFI_GUID              ReferenceGuid       The observable guid that the callback interface will subscribe to.
 *          OBS_CASLLBACK         CallbackInterface   A pointer to the function that is subscribing to the observable.
 *
 * @return  EFI_SUCCESS           Successfully subscribed the interface to the observable guid.
 *          EFI_NOT_FOUND         No match could be found between the provided guid and existing observables.
 *          EFI_OUT_OF_RESOURCES  Could not subscribe to this observer due to resource limitations.
 *          EFI_INVALID_PARAMETER Interface is already subscribed to this observer.
 **/
EFI_STATUS
EFIAPI
Subscribe (
  IN      EFI_GUID        ReferenceGuid,
  IN      OBS_CALLBACK    CallbackInterface
  )
{
  EFI_STATUS  Status    = EFI_SUCCESS;
  OBS_TREE*   TempTree  = NULL;
  OBS_LEAF*   Last      = NULL;
  OBS_LEAF*   TempLeaf  = NULL;
  OBS_LEAF*   NewLeaf   = NULL;
  BOOLEAN     Found     = FALSE;

  if (mObservableDb != NULL) {
    //
    // Find the observable guid that we're looking for.
    //
    for (TempTree = mObservableDb; TempTree != NULL; TempTree = TempTree->Next) {
      if (CompareMem(&(TempTree->ObservableGuid), &ReferenceGuid, sizeof(ReferenceGuid)) == 0) {
        Found = TRUE;
        break;
      }
    }
    if (Found) {
      //
      // Prepare to add a new leaf.
      //
      NewLeaf = AllocateZeroPool(sizeof(OBS_LEAF));
      if (!NewLeaf) {
        Status = EFI_OUT_OF_RESOURCES;
      } else {
        NewLeaf->Next = NULL;
        NewLeaf->Observer = CallbackInterface;
        //
        // Go to the end of the list of observers.
        //
        if (TempTree->Leaf != NULL) {
          //
          // First check to see if this is a duplicate observer.
          //
          Found = FALSE;
          TempLeaf = TempTree->Leaf;
          do {
            Last = TempLeaf;
            if (TempLeaf->Observer == CallbackInterface) {
              //
              // It is, so let's abort this process.
              //
              Found = TRUE;
              break;
            }
            TempLeaf = TempLeaf->Next;
          } while (TempLeaf != NULL);
          TempLeaf = Last;

          //
          // Check for duplicates.
          //
          if (Found) {
            gBS->FreePool(NewLeaf);
            Status = EFI_INVALID_PARAMETER;
          } else {
            //
            // At this point, TempLeaf->Next will be the end of the list.
            //
            TempLeaf->Next = NewLeaf;
          }
        } else {
          //
          // There are no observers listening to this guid. Start a new list.
          //
          TempTree->Leaf = NewLeaf;
        }
      }
    } else {
      Status = EFI_NOT_FOUND;
    }
  } else {
    Status = EFI_NOT_FOUND;
  }

  return Status;
}

/** Unsubscribe an interface with an observable guid.
 *
 * Use this to remove an interface from the callback list associated with an observable guid.
 *
 * @param   EFI_GUID                ReferenceGuid   The observable guid to unsubscribe the interface from.
 *          OBS_NOTIFY_INTERFACE    NotifyCallback  A pointer to the interface that is being unsubscribed.
 *
 * @return  EFI_SUCCESS           Successfully unsubscribed the interface from the observable guid.
 **/
EFI_STATUS
EFIAPI
Unsubscribe (
  IN      EFI_GUID        ReferenceGuid,
  IN      OBS_CALLBACK    CallbackInterface
  )
{
  mObservableDb = FindAndDeleteSubscriber(mObservableDb, ReferenceGuid, CallbackInterface);

  return EFI_SUCCESS;
}

/** Notify observing functions.
 *
 * Use this to notify all functions who are subscribed to the guid specified by ReferenceGuid.
 *
 * @param   EFI_GUID          ReferenceGuid   The observable guid that contains the the list of interfaces to be notified.
 *          VOID*             Data            Parameter context to be passed to the notification function.
 *
 * @return  EFI_SUCCESS       Successfully notified all observers listening to this guid.
 *          EFI_NOT_FOUND     No match could be found between the provided guid and existing observables.
 **/
EFI_STATUS
EFIAPI
Publish (
  IN      EFI_GUID                  ReferenceGuid,
  IN  OUT VOID*                     Data
  )
{
  EFI_STATUS  Status    = EFI_SUCCESS;
  OBS_TREE*   TempTree  = NULL;
  OBS_LEAF*   TempLeaf  = NULL;
  BOOLEAN     Found     = FALSE;

  if (mObservableDb != NULL) {
    //
    // Find the observable guid that we're looking for.
    //
    for (TempTree = mObservableDb; TempTree != NULL; TempTree = TempTree->Next) {
      if (CompareMem(&(TempTree->ObservableGuid), &ReferenceGuid, sizeof(ReferenceGuid)) == 0) {
        Found = TRUE;
        break;
      }
    }
    if (Found) {
      //
      // Notify every listener by performing each provided callback.
      //
      for (TempLeaf = TempTree->Leaf; TempLeaf != NULL; TempLeaf = TempLeaf->Next) {
        if (TempLeaf->Observer != NULL) {
          //
          // Execute the callback.
          //
          TempLeaf->Observer(Data);
        }
      }
    } else {
      Status = EFI_NOT_FOUND;
    }
  } else {
    Status = EFI_NOT_FOUND;
  }

  return Status;
}

/** Creates a new observable.
 *
 * Create a new observable that can be observed with the use of Subscribe function.
 *
 * @param   EFI_GUID              ReferenceGuid   The observable guid to add.
 *
 * @return  EFI_SUCCESS           Successfully added observable.
 *          EFI_INVALID_PARAMETER Observable already exists.
 **/
EFI_STATUS
EFIAPI
AddObservable (
  IN      EFI_GUID                  ReferenceGuid
  )
{
  EFI_STATUS  Status    = EFI_SUCCESS;
  OBS_TREE*   TempTree  = NULL;
  OBS_TREE*   Last      = NULL;
  OBS_TREE*   NewTree   = NULL;
  BOOLEAN     Found     = FALSE;

  if (mObservableDb != NULL) {
    if (mObservableDb->Next != NULL) {
      //
      // Iterate to the end of the observable list while checking to see if we aren't creating a duplicate.
      //
      TempTree = mObservableDb->Next;
      do {
        Last = TempTree;
        if (CompareMem(&(TempTree->ObservableGuid), &ReferenceGuid, sizeof(ReferenceGuid)) == 0) {
          Found = TRUE;
          break;
        }
        TempTree = TempTree->Next;
      } while (TempTree != NULL);
      TempTree = Last;
    } else {
      TempTree = mObservableDb;
    }
    if (Found) {
      //
      // Duplicate, so reject the parameter.
      //
      Status = EFI_INVALID_PARAMETER;
    } else {
      //
      // TempTree->Next is our target. Prepare to add a new tree link.
      //
      NewTree = AllocateZeroPool(sizeof(OBS_TREE));
      if (NewTree) {
        NewTree->Next = NULL;
        NewTree->Leaf = NULL;
        CopyMem(&(NewTree->ObservableGuid), &ReferenceGuid, sizeof(ReferenceGuid));
        TempTree->Next = NewTree;
      } else {
        Status = EFI_OUT_OF_RESOURCES;
      }
    }
  } else {
    //
    // mObservableDb has not been created yet. Let's do that.
    //
    NewTree = AllocateZeroPool(sizeof(OBS_TREE));
    if (NewTree) {
      NewTree->Next = NULL;
      NewTree->Leaf = NULL;
      CopyMem(&(NewTree->ObservableGuid), &ReferenceGuid, sizeof(ReferenceGuid));
      mObservableDb = NewTree;
    } else {
      Status = EFI_OUT_OF_RESOURCES;
    }
  }

  return Status;
}

/** Remove an observable.
 *
 * Remove an observable so that it can no longer be subscribed to. In addition, unsubscribe any functions
 * that are subscribed to this guid.
 *
 * @param   EFI_GUID              ReferenceGuid   The observable guid to remove.
 *
 * @return  EFI_SUCCESS           Successfully removed observable.
 **/
EFI_STATUS
EFIAPI
RemoveObservable (
  IN      EFI_GUID        ReferenceGuid
  )
{
  mObservableDb = FindAndDeleteObservable(mObservableDb, ReferenceGuid);

  return EFI_SUCCESS;
}