Add thread-safe IdAllocator utility and example

Introduces a generic, thread-safe IdAllocator for generating unique 32-bit IDs with type and sequence information. Adds implementation, header, and a comprehensive example demonstrating allocation, validation, decomposition, thread safety, and counter reset. Updates CMakeLists and README to include the new example and mark the project as work in progress.

Author: lijy91

CMakeLists.txt

@@ -8,6 +8,7 @@ add_subdirectory(src)
 # Add example programs subdirectory
 add_subdirectory(examples/display_example)
 add_subdirectory(examples/display_c_example)
+add_subdirectory(examples/id_allocator_example)
 add_subdirectory(examples/keyboard_example)
 add_subdirectory(examples/menu_example)
 add_subdirectory(examples/menu_c_example)

README.md

@@ -2,6 +2,8 @@
 
 A modern cross-platform C++ library providing seamless, unified access to native system APIs across multiple platforms.
 
+🚧 Work in Progress: This package is currently under active development.
+
 ## Requirements
 
 ### Build Requirements

examples/id_allocator_example/CMakeLists.txt

@@ -0,0 +1,11 @@
+cmake_minimum_required(VERSION 3.10)
+
+# Set C++ standard
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Create executable for ID allocator example
+add_executable(id_allocator_example main.cpp)
+
+# Link against the nativeapi library
+target_link_libraries(id_allocator_example nativeapi)

examples/id_allocator_example/main.cpp

@@ -0,0 +1,177 @@
+#include <algorithm>
+#include <chrono>
+#include <iostream>
+#include <mutex>
+#include <thread>
+#include <vector>
+#include "../../src/foundation/id_allocator.h"
+
+using namespace nativeapi;
+
+// Define some example types for demonstration
+struct Window {};
+struct Menu {};
+struct MenuItem {};
+struct TrayIcon {};
+struct Display {};
+
+int main() {
+  std::cout << "IdAllocator Template Example" << std::endl;
+  std::cout << "============================" << std::endl;
+
+  // Example 1: Basic allocation for different object types
+  std::cout << "\n1. Basic Allocation:" << std::endl;
+
+  auto window_id = IdAllocator::Allocate<Window>();
+  auto menu_id = IdAllocator::Allocate<Menu>();
+  auto tray_id = IdAllocator::Allocate<TrayIcon>();
+
+  std::cout << "Window ID: 0x" << std::hex << window_id << std::dec
+            << " (Type: " << IdAllocator::GetType(window_id)
+            << ", Sequence: " << IdAllocator::GetSequence(window_id) << ")"
+            << std::endl;
+
+  std::cout << "Menu ID: 0x" << std::hex << menu_id << std::dec
+            << " (Type: " << IdAllocator::GetType(menu_id)
+            << ", Sequence: " << IdAllocator::GetSequence(menu_id) << ")"
+            << std::endl;
+
+  std::cout << "Tray ID: 0x" << std::hex << tray_id << std::dec
+            << " (Type: " << IdAllocator::GetType(tray_id)
+            << ", Sequence: " << IdAllocator::GetSequence(tray_id) << ")"
+            << std::endl;
+
+  // Example 2: TryAllocate with error checking
+  std::cout << "\n2. TryAllocate (safer allocation):" << std::endl;
+
+  auto maybe_id = IdAllocator::TryAllocate<MenuItem>();
+  if (maybe_id != IdAllocator::kInvalidId) {
+    std::cout << "MenuItem ID allocated successfully: 0x" << std::hex
+              << maybe_id << std::dec << std::endl;
+  } else {
+    std::cout << "MenuItem ID allocation failed" << std::endl;
+  }
+
+  // Example 3: ID validation and decomposition
+  std::cout << "\n3. ID Validation and Decomposition:" << std::endl;
+
+  std::cout << "Is window_id valid? "
+            << (IdAllocator::IsValid(window_id) ? "Yes" : "No") << std::endl;
+
+  auto decomposed = IdAllocator::Decompose(window_id);
+  std::cout << "Window ID decomposed - Type: " << decomposed.first
+            << ", Sequence: " << decomposed.second << std::endl;
+
+  // Example 4: Current count query
+  std::cout << "\n4. Current Counter Query:" << std::endl;
+
+  std::cout << "Current Window counter (before allocation): "
+            << IdAllocator::GetCurrentCount<Window>() << std::endl;
+
+  auto new_window_id = IdAllocator::Allocate<Window>();
+  std::cout << "New Window ID: 0x" << std::hex << new_window_id << std::dec
+            << " (Sequence: " << IdAllocator::GetSequence(new_window_id) << ")"
+            << std::endl;
+
+  std::cout << "Current Window counter (after allocation): "
+            << IdAllocator::GetCurrentCount<Window>() << std::endl;
+
+  // Example 5: Multiple allocations
+  std::cout << "\n5. Multiple Allocations:" << std::endl;
+
+  std::vector<IdAllocator::IdType> window_ids;
+  for (int i = 0; i < 5; ++i) {
+    window_ids.push_back(IdAllocator::Allocate<Window>());
+  }
+
+  std::cout << "Allocated " << window_ids.size() << " Window IDs:" << std::endl;
+  for (size_t i = 0; i < window_ids.size(); ++i) {
+    std::cout << "  ID " << (i + 1) << ": 0x" << std::hex << window_ids[i]
+              << std::dec
+              << " (Sequence: " << IdAllocator::GetSequence(window_ids[i])
+              << ")" << std::endl;
+  }
+
+  // Example 6: Thread safety demonstration
+  std::cout << "\n6. Thread Safety Demonstration:" << std::endl;
+
+  std::vector<std::thread> threads;
+  std::vector<IdAllocator::IdType> thread_ids;
+  std::mutex ids_mutex;
+
+  const int num_threads = 3;
+  const int ids_per_thread = 10;
+
+  auto start_time = std::chrono::high_resolution_clock::now();
+
+  for (int i = 0; i < num_threads; ++i) {
+    threads.emplace_back([&thread_ids, &ids_mutex, ids_per_thread, i]() {
+      std::vector<IdAllocator::IdType> local_ids;
+
+      for (int j = 0; j < ids_per_thread; ++j) {
+        auto id = IdAllocator::Allocate<Display>();
+        local_ids.push_back(id);
+      }
+
+      {
+        std::lock_guard<std::mutex> lock(ids_mutex);
+        thread_ids.insert(thread_ids.end(), local_ids.begin(), local_ids.end());
+      }
+    });
+  }
+
+  for (auto& thread : threads) {
+    thread.join();
+  }
+
+  auto end_time = std::chrono::high_resolution_clock::now();
+  auto duration = std::chrono::duration_cast<std::chrono::microseconds>(
+      end_time - start_time);
+
+  std::cout << "Allocated " << thread_ids.size() << " Display IDs from "
+            << num_threads << " threads in " << duration.count()
+            << " microseconds" << std::endl;
+
+  // Verify all IDs are unique
+  std::sort(thread_ids.begin(), thread_ids.end());
+  auto it = std::unique(thread_ids.begin(), thread_ids.end());
+  std::cout << "All IDs are unique: " << (it == thread_ids.end() ? "Yes" : "No")
+            << std::endl;
+
+  // Example 7: Different object types
+  std::cout << "\n7. Different Object Types:" << std::endl;
+
+  auto display_id = IdAllocator::Allocate<Display>();
+
+  std::cout << "Display ID: 0x" << std::hex << display_id << std::dec
+            << " (Type: " << IdAllocator::GetType(display_id) << ")"
+            << std::endl;
+
+  // Example 8: Reset functionality (for testing)
+  std::cout << "\n8. Reset Functionality:" << std::endl;
+
+  std::cout << "Menu counter before reset: "
+            << IdAllocator::GetCurrentCount<Menu>() << std::endl;
+  IdAllocator::Reset<Menu>();
+  std::cout << "Menu counter after reset: "
+            << IdAllocator::GetCurrentCount<Menu>() << std::endl;
+
+  auto new_menu_id = IdAllocator::Allocate<Menu>();
+  std::cout << "New Menu ID after reset: 0x" << std::hex << new_menu_id
+            << std::dec
+            << " (Sequence: " << IdAllocator::GetSequence(new_menu_id) << ")"
+            << std::endl;
+
+  // Example 9: Independent types after reset
+  std::cout << "\n9. Independent Types After Reset:" << std::endl;
+
+  auto window_after_reset = IdAllocator::Allocate<Window>();
+  std::cout << "Window ID after Menu reset: 0x" << std::hex
+            << window_after_reset << std::dec
+            << " (Sequence: " << IdAllocator::GetSequence(window_after_reset)
+            << ")" << std::endl;
+  std::cout << "Window counter was not affected by Menu reset" << std::endl;
+
+  std::cout << "\nExample completed successfully!" << std::endl;
+  return 0;
+}

include/nativeapi.h

@@ -8,6 +8,7 @@
 #include "../src/foundation/event.h"
 #include "../src/foundation/event_emitter.h"
 #include "../src/foundation/geometry.h"
+#include "../src/foundation/id_allocator.h"
 #include "../src/keyboard_event.h"
 #include "../src/keyboard_monitor.h"
 #include "../src/menu.h"

src/foundation/id_allocator.cpp

@@ -0,0 +1,58 @@
+/**
+ * Implementation of IdAllocator static methods for ID querying and validation.
+ */
+
+#include "id_allocator.h"
+
+namespace nativeapi {
+
+/**
+ * Extracts the type from an ID.
+ */
+uint32_t IdAllocator::GetType(IdType id) {
+  // Extract type value from high 8 bits (bits 31-24)
+  // kTypeMask = 0xFF000000, kTypeShift = 24
+  const uint32_t type_value = (id & kTypeMask) >> kTypeShift;
+  return type_value;
+}
+
+/**
+ * Extracts the sequence number from an ID.
+ */
+uint32_t IdAllocator::GetSequence(IdType id) {
+  // Extract sequence number from low 24 bits (bits 23-0)
+  // kSequenceMask = 0x00FFFFFF
+  return id & kSequenceMask;
+}
+
+/**
+ * Checks if an ID is valid.
+ */
+bool IdAllocator::IsValid(IdType id) {
+  // Extract type value from high 8 bits
+  const uint32_t type_value = (id & kTypeMask) >> kTypeShift;
+  
+  // Extract sequence number from low 24 bits
+  const uint32_t seq = id & kSequenceMask;
+  
+  // ID is valid if:
+  // 1. Type value is in valid range [kMinTypeValue, kMaxTypeValue] (1-10)
+  // 2. Sequence number is non-zero (0 is reserved for kInvalidId)
+  return IsValidType(type_value) && seq != 0u;
+}
+
+/**
+ * Extracts both type and sequence from an ID.
+ */
+std::pair<uint32_t, uint32_t> IdAllocator::Decompose(IdType id) {
+  // Extract type value from high 8 bits (bits 31-24)
+  const uint32_t type_value = (id & kTypeMask) >> kTypeShift;
+  
+  // Extract sequence number from low 24 bits (bits 23-0)
+  const uint32_t sequence = id & kSequenceMask;
+  
+  // Return both components as a pair
+  return {type_value, sequence};
+}
+
+}  // namespace nativeapi