WPILibC++ 2023.4.3
IndexedHandleResource.h
Go to the documentation of this file.
1// Copyright (c) FIRST and other WPILib contributors.
2// Open Source Software; you can modify and/or share it under the terms of
3// the WPILib BSD license file in the root directory of this project.
4
5#pragma once
6
7#include <stdint.h>
8
9#include <array>
10#include <memory>
11
12#include <wpi/mutex.h>
13
14#include "hal/Errors.h"
15#include "hal/Types.h"
17
18namespace hal {
19
20/**
21 * The IndexedHandleResource class is a way to track handles. This version
22 * allows a limited number of handles that are allocated by index.
23 * Because they are allocated by index, each individual index holds its own
24 * mutex, which reduces contention heavily.]
25 *
26 * @tparam THandle The Handle Type (Must be typedefed from HAL_Handle)
27 * @tparam TStruct The struct type held by this resource
28 * @tparam size The number of resources allowed to be allocated
29 * @tparam enumValue The type value stored in the handle
30 *
31 */
32template <typename THandle, typename TStruct, int16_t size,
33 HAL_HandleEnum enumValue>
36
37 public:
41
42 std::shared_ptr<TStruct> Allocate(int16_t index, THandle* handle,
44 int16_t GetIndex(THandle handle) {
45 return getHandleTypedIndex(handle, enumValue, m_version);
46 }
47 std::shared_ptr<TStruct> Get(THandle handle);
48 void Free(THandle handle);
49 void ResetHandles() override;
50
51 private:
52 std::array<std::shared_ptr<TStruct>, size> m_structures;
53 std::array<wpi::mutex, size> m_handleMutexes;
54};
55
56template <typename THandle, typename TStruct, int16_t size,
57 HAL_HandleEnum enumValue>
58std::shared_ptr<TStruct>
60 int16_t index, THandle* handle, int32_t* status) {
61 // don't acquire the lock if we can fail early.
62 if (index < 0 || index >= size) {
64 *handle = HAL_kInvalidHandle;
65 return nullptr;
66 }
67 std::scoped_lock lock(m_handleMutexes[index]);
68 // check for allocation, otherwise allocate and return a valid handle
69 if (m_structures[index] != nullptr) {
71 *handle = HAL_kInvalidHandle;
72 return m_structures[index];
73 }
74 m_structures[index] = std::make_shared<TStruct>();
75 *handle =
76 static_cast<THandle>(hal::createHandle(index, enumValue, m_version));
78 return m_structures[index];
79}
80
81template <typename THandle, typename TStruct, int16_t size,
82 HAL_HandleEnum enumValue>
83std::shared_ptr<TStruct>
85 // get handle index, and fail early if index out of range or wrong handle
86 int16_t index = GetIndex(handle);
87 if (index < 0 || index >= size) {
88 return nullptr;
89 }
90 std::scoped_lock lock(m_handleMutexes[index]);
91 // return structure. Null will propagate correctly, so no need to manually
92 // check.
93 return m_structures[index];
94}
95
96template <typename THandle, typename TStruct, int16_t size,
97 HAL_HandleEnum enumValue>
99 THandle handle) {
100 // get handle index, and fail early if index out of range or wrong handle
101 int16_t index = GetIndex(handle);
102 if (index < 0 || index >= size) {
103 return;
104 }
105 // lock and deallocated handle
106 std::scoped_lock lock(m_handleMutexes[index]);
107 m_structures[index].reset();
108}
109
110template <typename THandle, typename TStruct, int16_t size,
111 HAL_HandleEnum enumValue>
113 for (int i = 0; i < size; i++) {
114 std::scoped_lock lock(m_handleMutexes[i]);
115 m_structures[i].reset();
116 }
118}
119} // namespace hal
Base for all HAL Handles.
Definition: HandlesInternal.h:28
virtual void ResetHandles()
int16_t m_version
Definition: HandlesInternal.h:38
The IndexedHandleResource class is a way to track handles.
Definition: IndexedHandleResource.h:34
void ResetHandles() override
Definition: IndexedHandleResource.h:112
friend class IndexedHandleResourceTest
Definition: IndexedHandleResource.h:35
int16_t GetIndex(THandle handle)
Definition: IndexedHandleResource.h:44
std::shared_ptr< TStruct > Get(THandle handle)
Definition: IndexedHandleResource.h:84
void Free(THandle handle)
Definition: IndexedHandleResource.h:98
IndexedHandleResource & operator=(const IndexedHandleResource &)=delete
std::shared_ptr< TStruct > Allocate(int16_t index, THandle *handle, int32_t *status)
Definition: IndexedHandleResource.h:59
IndexedHandleResource(const IndexedHandleResource &)=delete
#define RESOURCE_OUT_OF_RANGE
Definition: Errors.h:80
#define RESOURCE_IS_ALLOCATED
Definition: Errors.h:78
#define HAL_SUCCESS
Definition: Errors.h:44
#define HAL_kInvalidHandle
Definition: Types.h:15
EIGEN_CONSTEXPR Index size(const T &x)
Definition: Meta.h:479
::int16_t int16_t
Definition: Meta.h:55
::int32_t int32_t
Definition: Meta.h:57
GHC_FS_API file_status status(const path &p, std::error_code &ec) noexcept
Definition: filesystem.hpp:4892
WPILib Hardware Abstraction Layer (HAL) namespace.
Definition: ChipObject.h:40
HAL_HandleEnum
Enum of HAL handle types.
Definition: HandlesInternal.h:46
HAL_Handle createHandle(int16_t index, HAL_HandleEnum handleType, int16_t version)
Create a handle for a specific index, type and version.
int16_t getHandleTypedIndex(HAL_Handle handle, HAL_HandleEnum enumType, int16_t version)
Get if the handle is a correct type and version.
Definition: HandlesInternal.h:134