/*
  Copyright 2024 Northern.tech AS

  This file is part of CFEngine 3 - written and maintained by Northern.tech AS.

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.

  To the extent this program is licensed as part of the Enterprise
  versions of CFEngine, the applicable Commercial Open Source License
  (COSL) may apply to this file if you as a licensee so wish it. See
  included file COSL.txt.
*/

#ifndef CFENGINE_REFCOUNT_H
#define CFENGINE_REFCOUNT_H

#include <stdbool.h>

/**
  @brief Simple reference count implementation.

  Reference counting helps to keep track of elements and avoid unnecessary duplication.
  In C we need to manually keep track of the users, while in C++ this is implicitly done
  by the "this" pointer. If we don't do that and we just count how many users we have,
  we risk multiples attach or detach. We need one way to find out who is connected to
  the refcount so we can act properly.
  */
struct RefCountNode {
    struct RefCountNode *next;
    struct RefCountNode *previous;
    void *user;
};
typedef struct RefCountNode RefCountNode;

struct RefCount {
    // Normally one unless we are shared.
    unsigned int user_count;
    RefCountNode *users;
    RefCountNode *last;
};
typedef struct RefCount RefCount;

/**
  @brief Initializes a refcount structure.
  @param ref RefCount structure to be initialized.
  */
void RefCountNew(RefCount **ref);
/**
  @brief Destroys a refcount structure.
  @param ref RefCount structure to be destroyed.
  */
void RefCountDestroy(RefCount **ref);
/**
  @brief Attaches a data structure to a given RefCount structure.
  Attaching refers to the fact that the container is using a data structure that might be shared by others.
  This should be called before using the data structure so everybody is aware of the new holder.
  @param ref RefCountr structure
  @param owner Data structure to be attached.
  */
void RefCountAttach(RefCount *ref, void *owner);
/**
  @brief Detaches a data structure from a given RefCount structure.
  Detaching should be called after the container has copied the data structure. As long as the container is
  still using the data structure it should not detach from the reference counting. Otherwise this might lead
  to undesired side effects.
  @param ref RefCountr structure
  @param owner Data structure to be detached.
  */
void RefCountDetach(RefCount *ref, void *owner);
/**
  @brief Simple check to see if a given data structure is shared.
  @param ref RefCount structure.
  @return True if shared, false otherwise.
  */
bool RefCountIsShared(RefCount *ref);
/**
  @brief Compares two RefCount structures.
  @param a
  @param b
  @return True if a and b point to the same object, false otherwise.
  @remarks This function is needed in order to speed up comparisons of complex
  data structures. If the RefCount objects of the two structures are the same,
  then most likely the structures are the same.
  */
bool RefCountIsEqual(RefCount *a, RefCount *b);

#endif // CFENGINE_REFCOUNT_H
