Registered Opaques

README.md

Registered Opaques

Copyright (c) 2023, Roy Ratcliffe, Northumberland, United Kingdom

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

registered_opaques.c

/*
 * registered_opaques.c
 *
 * The registered opaque structure has no counter. The number of registered
 * opaque pointers corresponds to the total number of pointers less the number
 * of \c NULL pointers.
 */

#include "registered_opaques.h"

/*
 * Only for \c configASSERT macro.
 */
#include "FreeRTOS.h"
#include "task.h"

static void **ppvRegisteredOpaque(RegisteredOpaques_t xRegisteredOpaques,
                                  void *pvOpaque, size_t xCardinal);

static size_t xRegisteredHashOfOpaque(RegisteredOpaques_t xRegisteredOpaques,
                                      void *pvOpaque);

size_t xRegisteredCardinalOfOpaque(RegisteredOpaques_t xRegisteredOpaques,
                                   void *pvOpaque) {
  size_t xCardinal = xRegisteredHashOfOpaque(xRegisteredOpaques, pvOpaque);
  void **ppvOpaque =
      ppvRegisteredOpaque(xRegisteredOpaques, pvOpaque, xCardinal);
  if (ppvOpaque == NULL) {
    ppvOpaque = ppvRegisteredOpaque(xRegisteredOpaques, NULL, xCardinal);
    configASSERT(ppvOpaque);
    *ppvOpaque = pvOpaque;
  }
  return ppvOpaque - xRegisteredOpaques->ppvOpaques;
}

/*!
 * \brief Searches for an opaque pointer.
 *
 * \param xCardinal Starting cardinal typically based on the opaque's hash. Must
 * always be less than the number of opaque pointers.
 *
 * \returns Pointer to opaque pointer.
 *
 * The implementation design optimises for quickly finding a
 * previously-registered opaque. For example, it would be possible to collate
 * the \c NULL opaques while iterating.
 */
static void **ppvRegisteredOpaque(RegisteredOpaques_t xRegisteredOpaques,
                                  void *pvOpaque, size_t xCardinal) {
  for (size_t xOrdinal = xRegisteredOpaques->xNumberOfOpaques; xOrdinal;
       xOrdinal--) {
    void **ppvRegisteredOpaque = xRegisteredOpaques->ppvOpaques + xCardinal;
    if (*ppvRegisteredOpaque == pvOpaque)
      return ppvRegisteredOpaque;
    if (++xCardinal == xRegisteredOpaques->xNumberOfOpaques)
      xCardinal = 0U;
  }
  return NULL;
}

/*!
 * \brief Computes the hash of an opaque pointer.
 * \returns Optimised cardinal offset of opaque pointer based on hash function,
 * or zero by default.
 */
static size_t xRegisteredHashOfOpaque(RegisteredOpaques_t xRegisteredOpaques,
                                      void *pvOpaque) {
  if (xRegisteredOpaques->pxHashOfOpaqueFunction == NULL)
    return 0U;
  return xRegisteredOpaques->pxHashOfOpaqueFunction(pvOpaque) %
         xRegisteredOpaques->xNumberOfOpaques;
}

registered_opaques.h

/*
 * registered_opaques.h (Abstractions)
 */

/*!
 * \file
 *
 * The link to FreeRTOS is tenuous. Only the asserts utilise FreeRTOS \c
 * configASSERT for memory overruns. The naming conventions echo FreeRTOS
 * Hungarian naming conventions.
 */

#pragma once

#include <stddef.h>

struct RegisteredOpaques {
  void **ppvOpaques;
  size_t xNumberOfOpaques;
  size_t (*pxHashOfOpaqueFunction)(void *pvOpaque);
};

typedef struct RegisteredOpaques *RegisteredOpaques_t;

/*!
 * \brief Cardinal for opaque pointer.
 *
 * Registers the opaque pointer if not already registered. Uses the hash
 * function, if available, to place the opaque in a hash-optimised registry
 * location.
 *
 * Asserts if full. By design, always provide sufficient space for registered
 * opaque pointers. No function exists to unregister a pointer by design.
 */
size_t xRegisteredCardinalOfOpaque(RegisteredOpaques_t xRegisteredOpaques,
                                   void *pvOpaque);