Base API
2026-10-10 audit: this page was rewritten against the actual state of HEAD (eight
modules/baseheaders: time/thread_pool/id_pool/memory/string/rng/ terminal/timer_wheel). The old draft'sTime::nowMillis(),IdPool::acquire(), the standalone<apollo/base/object_pool.hpp>header etc. do not exist in the repository.
apollo::base::Time(time.hpp)
namespace apollo::base {
class Time {
public:
using Timestamp = int64_t;
static Timestamp now(); // steady_clock milliseconds
static int64_t now_microseconds();
static int64_t now_nanoseconds();
static time_t unix_time();
static std::string format(time_t timestamp,
const char* pattern = "%Y-%m-%d %H:%M:%S");
};
}The same file also provides:
Timer——reset()/elapsed()(seconds,double).ScopeTimer——RAII timing (starts on construction, logs on destruction).FpsCalculator——update()feeds per frame,fps()reads the sliding frame rate (refresh interval injected at construction, default 500ms).
Thread safety: safe (all static, stateless)
apollo::base::ThreadPool(thread_pool.hpp)
namespace apollo::base {
class ThreadPool {
public:
explicit ThreadPool(size_t threads);
~ThreadPool(); // destruction stops it
template<class F, class... Args>
auto submit(F&& f, Args&&... args)
-> std::future<std::invoke_result_t<F, Args...>>;
// submit after stop throws std::runtime_error
size_t thread_count() const; // thread count
size_t pending_task_count() const; // queued task count
void wait_for_all(); // wait for all tasks to finish
void stop(); // stop (unexecuted tasks are dropped)
};
}Thread safety: safe (internal locks)
apollo::base::IdPool(id_pool.hpp)
namespace apollo::base {
class IdPool {
public:
IdPool() = default;
IdPool(uint32_t min_id, uint32_t max_id); // range [min_id, max_id]
explicit IdPool(uint32_t size); // [0, size)
uint32_t allocate(); // allocate (UINT32_MAX when exhausted)
void release(uint32_t id);
bool reserve(uint32_t id); // pre-reserve a specific id
void reset();
bool is_valid(uint32_t id) const;
bool is_allocated(uint32_t id) const;
bool is_full() const;
bool is_empty() const;
uint32_t allocated_count() const;
uint32_t capacity() const;
uint32_t usage_percent() const;
};
}Thread safety: unsafe (belongs to the host thread; no internal locks)
apollo::base::ObjectPool(id_pool.hpp, slot-reuse IdPool mechanism)
namespace apollo::base {
template <typename T>
class ObjectPool {
public:
explicit ObjectPool(uint32_t capacity);
uint32_t allocate(T object); // slot-based holding, returns id (UINT32_MAX when exhausted)
T* get(uint32_t id); // out-of-range/free returns nullptr
std::unique_ptr<T> release(uint32_t id);// take out and free the slot
};
}Note: unlike the old draft, this is not acquire()/release(shared_ptr) semantics — the caller constructs the object, allocate(std::move(obj)) puts it in the pool, get(id) accesses it, and release(id) takes it out.
Thread safety: unsafe (no internal locks)
apollo::base::String(string.hpp)
namespace apollo::base {
class String {
public:
// trimming (incl. ltrim/rtrim and *_in_place variants)
static std::string trim(std::string_view str);
static void trim_in_place(std::string& str);
// case
static std::string to_lower(std::string str);
static std::string to_upper(std::string str);
// comparison
static bool iequals(std::string_view a, std::string_view b);
static bool starts_with(std::string_view str, std::string_view prefix);
static bool ends_with(std::string_view str, std::string_view suffix);
static bool istarts_with(std::string_view str, std::string_view prefix);
static bool iends_with(std::string_view str, std::string_view suffix);
// splitting (string_view delimiter overload + out-parameter overload)
static std::vector<std::string> split(std::string_view str, char delimiter);
// joining (two overloads: vector<string> and vector<string_view>)
static std::string join(const std::vector<std::string>& strs, std::string_view delimiter);
// formatting
template <typename... Args>
static std::string format(const char* fmt, Args... args);
static std::string format_bytes(uint64_t bytes); // humanize a byte count
};
}Thread safety: safe (all static, stateless)
apollo::base::FixedMemoryPool(memory.hpp)
namespace apollo::base {
template <size_t BlockSize, size_t BlockCount = 1024>
class FixedMemoryPool {
public:
FixedMemoryPool(); // capacity fixed at compile time by BlockCount
void* allocate(); // nullptr when exhausted
void deallocate(void* ptr);
size_t allocated_count() const;
size_t capacity() const; // = BlockCount
size_t block_size() const; // = BlockSize (>= sizeof(void*))
};
}Thread safety: safe (internal mutex)
The same file also provides:
ByteBuffer——ByteBuffer(capacity = 1024),write(const void*, len)/ read-pointer surface /data()/size()/capacity()/empty()(byte buffer).ArenaAllocator——ArenaAllocator(initial_capacity = 4096), arena allocation +construct<T>(args...)placement construction (batches of small objects, released together).
apollo::base::Pcg32(rng.hpp)
A minimal PCG-XSH-RR 64/32 implementation (deterministic substreams — the same source as the combat random stream battle-determinism):
namespace apollo::base {
class Pcg32 {
public:
Pcg32() = default;
void seed(std::uint64_t initstate, std::uint64_t stream); // substream oddification built in
std::uint32_t next_uint32() noexcept;
double next_double() noexcept; // [0, 1)
};
}Thread safety: unsafe (single stream, single writer; cross-stream isolation via the stream parameter)
apollo::base::Terminal(terminal.hpp)
A static terminal utility surface: is_tty() / supports_color() / enable_color() / get_size() (Size{rows, cols}) / clear() / clear_line() / move_cursor(row, col) / cursor_up/down/left/right(n) / save_cursor() etc.
Thread safety: unsafe (global terminal state)
apollo::base::TimerWheel(timer_wheel.hpp, G-4 timer wheel library component)
A hierarchical hashed timing wheel (single-writer lock-free; the driving right belongs to the game loop — advance(now_ms) feeds the clock):
namespace apollo::base {
class TimerWheel {
public:
using TimerId = std::uint64_t; // (generation << 32) | slot number; 0 = invalid
using Callback = std::function<void(TimerId)>;
explicit TimerWheel(std::uint32_t tick_ms = 10, std::uint32_t slots = 64,
std::uint32_t levels = 5, std::uint64_t start_ms = 0);
TimerId schedule_after(std::uint64_t delay_ms, Callback cb); // one-shot
TimerId schedule_interval(std::uint64_t interval_ms, Callback cb); // periodic
bool cancel(TimerId id); // already-fired/stale id = false
void advance(std::uint64_t now_ms); // clock feed: fires due callbacks per tick
};
}Thread safety: unsafe (single-writer discipline — only the game loop thread may call it)
The base module does not include: logging, configuration, network, or framework semantics — those belong to core and above (base is pure infrastructure, usable standalone by any C++ project).
