【OpenHarmony】commonlibrary_c_utils完成

C++公共基础库（c_utils）模块

目录

  1. 模块概述
  2. 模块结构
  3. 模块间交互
  4. 状态机转换图
  5. 接口设计

1. 模块概述

源码：https://gitee.com/openharmony/commonlibrary_c_utils/tree/master

1.1 功能与目标

主要功能

C++公共基础类库（c_utils）为OpenHarmony标准系统提供了一套常用的C++开发工具类，主要包括以下功能模块：

功能模块描述
智能指针管理提供sptr/wptr智能指针，实现自动内存管理和引用计数
数据序列化提供Parcel数据容器，支持IPC/RPC场景下的数据序列化与反序列化
线程与同步提供线程类、线程池、读写锁、信号量等多线程编程工具
安全数据容器提供线程安全的Map、Queue、Vector等容器
文件与目录操作提供文件读写、目录操作、文件映射等增强接口
定时器提供定时器管理功能，支持单次和循环定时事件
事件处理提供IO事件反应器，支持epoll事件驱动模型
设计模式提供单例模式、观察者模式等常用设计模式实现
匿名共享内存提供Ashmem操作接口，支持进程间内存共享
设计目标
  1. 通用性: 提供跨子系统的通用基础能力
  2. 安全性: 提供线程安全的数据结构和操作接口
  3. 高性能: 优化内存管理和同步机制
  4. 易用性: 提供简洁统一的API接口
  5. 可扩展性: 支持Rust语言绑定扩展

1.2 系统位置

在系统中的位置

c_utils作为OpenHarmony系统的核心基础模块，位于系统架构的底层，为上层各子系统提供基础能力支撑。

graph TB
    subgraph 应用层
        APP[Applications]
    end
    subgraph 框架层
        AAFWK[AAFWK子系统]
        AppExec[AppExecFWK子系统]
        DFX[DFX子系统]
        Other[其他子系统]
    end
    subgraph 基础服务层
        subgraph c_utils[commonlibrary/c_utils]
            SmartPtr[智能指针]
            DataContainer[数据容器]
            ThreadMgmt[线程管理]
            FileOps[文件操作]
            Timer[定时器]
            EventProc[事件处理]
            DesignPattern[设计模式]
            SharedMem[共享内存]
        end
    end
    subgraph 内核层
        Linux[Linux Kernel]
        LiteOS[LiteOS]
        Driver[驱动框架]
    end
    APP --> AAFWK
    APP --> AppExec
    APP --> DFX
    APP --> Other
    AAFWK --> c_utils
    AppExec --> c_utils
    DFX --> c_utils
    Other --> c_utils
    c_utils --> Linux
    c_utils --> LiteOS
    c_utils --> Driver
与其他模块的关系
关系类型相关模块说明
被依赖IPC/RPC框架使用Parcel进行数据序列化
被依赖分布式数据管理使用智能指针和线程池
被依赖图形子系统使用共享内存和同步机制
依赖Linux内核使用epoll、ashmem等内核特性
依赖标准C++库使用STL容器和线程库

1.3 设计思路与模式

设计思路
  1. 分层设计: 将功能按职责分为不同层次，降低耦合度
  2. 模板化设计: 使用C++模板实现通用数据结构
  3. RAII原则: 资源获取即初始化，确保资源安全释放
  4. 线程安全: 所有公共接口保证线程安全
采用的设计模式
设计模式应用场景实现类
单例模式全局唯一实例管理Singleton, DelayedSingleton, DelayedRefSingleton
观察者模式事件通知机制Observable, Observer
工厂模式对象创建Ashmem::CreateAshmem()
RAII模式资源管理UniqueWriteGuard, UniqueReadGuard, sptr, wptr
反应器模式IO事件处理IOEventReactor, IOEventHandler
生产者-消费者模式任务队列SafeBlockQueue, ThreadPool

2. 模块结构

2.1 源文件与头文件

目录结构
commonlibrary/c_utils/
├── base/
│   ├── include/           # 公共头文件
│   │   ├── refbase.h      # 智能指针定义
│   │   ├── parcel.h       # 数据容器定义
│   │   ├── singleton.h    # 单例模式定义
│   │   ├── timer.h        # 定时器定义
│   │   ├── thread_pool.h  # 线程池定义
│   │   ├── thread_ex.h    # 线程类定义
│   │   ├── rwlock.h       # 读写锁定义
│   │   ├── safe_map.h     # 安全Map定义
│   │   ├── safe_queue.h   # 安全队列定义
│   │   ├── safe_block_queue.h  # 阻塞队列定义
│   │   ├── observer.h     # 观察者模式定义
│   │   ├── io_event_reactor.h  # IO事件反应器
│   │   ├── io_event_handler.h  # IO事件处理器
│   │   ├── ashmem.h       # 匿名共享内存
│   │   ├── mapped_file.h  # 文件映射
│   │   ├── file_ex.h      # 文件操作
│   │   ├── directory_ex.h # 目录操作
│   │   ├── string_ex.h    # 字符串操作
│   │   ├── datetime_ex.h  # 日期时间操作
│   │   ├── unique_fd.h    # 文件描述符管理
│   │   ├── sorted_vector.h # 有序向量
│   │   ├── semaphore_ex.h # 信号量
│   │   ├── nocopyable.h   # 禁止拷贝基类
│   │   ├── errors.h       # 错误码定义
│   │   └── ...
│   ├── src/               # 源文件
│   │   ├── refbase.cpp
│   │   ├── parcel.cpp
│   │   ├── timer.cpp
│   │   ├── thread_pool.cpp
│   │   ├── thread_ex.cpp
│   │   ├── rwlock.cpp
│   │   ├── observer.cpp
│   │   ├── io_event_reactor.cpp
│   │   ├── io_event_handler.cpp
│   │   ├── io_event_epoll.cpp
│   │   ├── ashmem.cpp
│   │   ├── mapped_file.cpp
│   │   ├── file_ex.cpp
│   │   ├── directory_ex.cpp
│   │   ├── string_ex.cpp
│   │   ├── datetime_ex.cpp
│   │   ├── semaphore_ex.cpp
│   │   └── rust/          # Rust绑定
│   │       ├── lib.rs
│   │       ├── ashmem.rs
│   │       ├── file_ex.rs
│   │       └── directory_ex.rs
│   └── test/              # 测试代码
│       ├── unittest/
│       ├── benchmarktest/
│       └── fuzztest/
└── docs/                  # 文档
    ├── en/
    └── zh-cn/
主要文件功能说明
文件功能描述
refbase.h/cpp实现引用计数基类和智能指针(sptr/wptr)
parcel.h/cpp实现数据序列化容器，支持基本类型和对象的读写
singleton.h实现三种单例模式模板类
timer.h/cpp实现定时器管理，支持注册/注销定时事件
thread_pool.h/cpp实现线程池，管理任务队列和工作线程
thread_ex.h/cpp实现线程封装类，提供线程生命周期管理
rwlock.h/cpp实现读写锁，支持写优先模式
safe_map.h实现线程安全的Map容器
safe_block_queue.h实现线程安全的阻塞队列
observer.h/cpp实现观察者设计模式
io_event_reactor.h/cpp实现IO事件反应器
ashmem.h/cpp实现匿名共享内存操作
mapped_file.h/cpp实现内存映射文件
file_ex.h/cpp实现文件读写增强功能
errors.h定义错误码格式和通用错误码

2.2 类、结构体、函数与方法

2.2.1 智能指针模块
RefCounter 类
class RefCounter {
public:
using RefPtrCallback = std::function<void()>;
  RefCounter();
  virtual ~RefCounter();
  // 引用计数操作
  int GetRefCount();
  void IncRefCount();
  void DecRefCount();
  // 强引用计数操作
  int IncStrongRefCount(const void *objectId);
  int DecStrongRefCount(const void *objectId);
  int GetStrongRefCount();
  // 弱引用计数操作
  int IncWeakRefCount(const void *objectId);
  int DecWeakRefCount(const void *objectId);
  int GetWeakRefCount();
  // 生命周期管理
  void ExtendObjectLifetime();
  bool IsLifeTimeExtended();
  // 尝试增加强引用
  bool AttemptIncStrongRef(const void *objectId, int &outCount);
  bool AttemptIncStrong(const void *objectId);
  private:
  std::atomic<int> atomicStrong_;    // 强引用计数
    std::atomic<int> atomicWeak_;      // 弱引用计数
      std::atomic<int> atomicRefCount_;  // RefCounter对象引用计数
        std::atomic<unsigned int> atomicFlags_; // 生命周期标志
          RefPtrCallback callback_;          // 释放回调
          };
RefBase 类
class RefBase {
public:
RefBase();
RefBase(const RefBase &);
RefBase &operator=(const RefBase &);
RefBase(RefBase &&other) noexcept;
RefBase &operator=(RefBase &&other) noexcept;
virtual ~RefBase();
// 强引用操作
void IncStrongRef(const void *objectId);
void DecStrongRef(const void *objectId);
int GetSptrRefCount();
// 弱引用操作
WeakRefCounter *CreateWeakRef(void *cookie);
void IncWeakRef(const void *objectId);
void DecWeakRef(const void *objectId);
int GetWptrRefCount();
// 生命周期管理
void ExtendObjectLifetime();
bool AttemptAcquire(const void *objectId);
bool AttemptIncStrongRef(const void *objectId);
// 回调函数（可重写）
virtual void OnFirstStrongRef(const void *);
virtual void OnLastStrongRef(const void *);
virtual void OnLastWeakRef(const void *);
private:
RefCounter *refs_;
};
sptr 模板类（强引用智能指针）
template <typename T>
  class sptr {
  public:
  sptr();
  ~sptr();
  sptr(T *other);
  sptr(const sptr<T> &other);
    sptr(sptr<T> &&other);
      // 工厂方法（推荐使用）
      template <typename... Args>
        static sptr<T> MakeSptr(Args&&... args);
          // 访问操作
          T *GetRefPtr() const;
          T &operator*() const;
          T *operator->() const;
          operator T*() const;
          explicit operator bool() const;
          // 赋值操作
          sptr<T> &operator=(T *other);
            sptr<T> &operator=(const sptr<T> &other);
              sptr<T> &operator=(sptr<T> &&other);
                // 比较操作
                bool operator==(const T *other) const;
                bool operator==(const sptr<T> &other) const;
                  void clear();
                  private:
                  T *refs_;
                  };
wptr 模板类（弱引用智能指针）
template <typename T>
  class wptr {
  public:
  wptr();
  ~wptr();
  wptr(T *other);
  wptr(const wptr<T> &other);
    wptr(const sptr<T> &other);
      // 访问操作
      T *GetRefPtr() const;
      T &operator*() const;
      T *operator->() const;
      // 提升为强引用
      const sptr<T> promote() const;
        bool AttemptIncStrongRef(const void *objectId) const;
        // 赋值操作
        wptr<T> &operator=(T *other);
          wptr<T> &operator=(const wptr<T> &other);
            wptr<T> &operator=(const sptr<T> &other);
              private:
              WeakRefCounter *refs_;
              };
2.2.2 数据容器模块
Parcelable 类
class Parcelable : public virtual RefBase {
public:
Parcelable();
explicit Parcelable(bool asRemote);
virtual ~Parcelable() = default;
// 序列化接口（必须实现）
virtual bool Marshalling(Parcel &parcel) const = 0;
// 行为标志
enum BehaviorFlag { IPC = 0x01, RPC = 0x02, HOLD_OBJECT = 0x10 };
void SetBehavior(BehaviorFlag b) const;
void ClearBehavior(BehaviorFlag b) const;
bool TestBehavior(BehaviorFlag b) const;
bool asRemote_;
mutable uint8_t behavior_;
};
Parcel 类
class Parcel {
public:
Parcel();
explicit Parcel(Allocator *allocator);
virtual ~Parcel();
// 容量管理
size_t GetDataSize() const;
size_t GetDataCapacity() const;
size_t GetWritableBytes() const;
size_t GetReadableBytes() const;
bool SetDataCapacity(size_t newCapacity);
bool SetMaxCapacity(size_t maxCapacity);
// 基本类型写入
bool WriteBool(bool value);
bool WriteInt8(int8_t value);
bool WriteInt16(int16_t value);
bool WriteInt32(int32_t value);
bool WriteInt64(int64_t value);
bool WriteUint8(uint8_t value);
bool WriteUint16(uint16_t value);
bool WriteUint32(uint32_t value);
bool WriteUint64(uint64_t value);
bool WriteFloat(float value);
bool WriteDouble(double value);
// 字符串写入
bool WriteCString(const char *value);
bool WriteString(const std::string &value);
bool WriteString16(const std::u16string &value);
// 缓冲区写入
bool WriteBuffer(const void *data, size_t size);
// 对象写入
bool WriteParcelable(const Parcelable *object);
bool WriteStrongParcelable(const sptr<Parcelable> &object);
  bool WriteRemoteObject(const Parcelable *object);
  // 基本类型读取
  bool ReadBool();
  int8_t ReadInt8();
  int16_t ReadInt16();
  int32_t ReadInt32();
  int64_t ReadInt64();
  // ... 其他类型
  // 字符串读取
  const char *ReadCString();
  const std::string ReadString();
  const std::u16string ReadString16();
  // 对象读取
  template <typename T>
    T *ReadParcelable();
    template <typename T>
      sptr<T> ReadStrongParcelable();
        // 游标操作
        bool RewindRead(size_t newPosition);
        bool RewindWrite(size_t offsets);
        size_t GetReadPosition();
        size_t GetWritePosition();
        // Vector读写
        bool WriteInt32Vector(const std::vector<int32_t> &val);
          bool ReadInt32Vector(std::vector<int32_t> *val);
            // ... 其他类型Vector
            private:
            uint8_t *data_;
            size_t readCursor_;
            size_t writeCursor_;
            size_t dataSize_;
            size_t dataCapacity_;
            Allocator *allocator_;
            };
2.2.3 线程管理模块
Thread 类
class Thread {
public:
Thread();
virtual ~Thread();
// 线程控制
ThreadStatus Start(const std::string& name,
int32_t priority = THREAD_PROI_NORMAL,
size_t stack = 0);
ThreadStatus NotifyExitSync();
virtual void NotifyExitAsync();
// 状态查询
virtual bool ReadyToWork();
bool IsExitPending() const;
bool IsRunning() const;
pthread_t GetThread() const;
protected:
// 子类必须实现
virtual bool Run() = 0;
private:
pthread_t thread_;
std::mutex lock_;
std::condition_variable cvThreadExited_;
ThreadStatus status_;
volatile bool exitPending_;
volatile bool running_;
};
ThreadPool 类
class ThreadPool : public NoCopyable {
public:
typedef std::function<void()> Task;
  explicit ThreadPool(const std::string &name = std::string());
  ~ThreadPool() override;
  // 线程池控制
  uint32_t Start(int threadsNum);
  void Stop();
  // 任务管理
  void AddTask(const Task& f);
  void SetMaxTaskNum(size_t maxSize);
  // 状态查询
  size_t GetMaxTaskNum() const;
  size_t GetCurTaskNum();
  size_t GetThreadsNum() const;
  std::string GetName() const;
  private:
  bool Overloaded() const;
  void WorkInThread();
  Task ScheduleTask();
  std::string myName_;
  std::mutex mutex_;
  std::condition_variable hasTaskToDo_;
  std::condition_variable acceptNewTask_;
  std::vector<std::thread> threads_;
    std::deque<Task> tasks_;
      size_t maxTaskNum_;
      bool running_;
      };
RWLock 类
class RWLock : NoCopyable {
public:
enum LockStatus {
LOCK_STATUS_WRITE = -1,
LOCK_STATUS_FREE = 0,
};
RWLock();
explicit RWLock(bool writeFirst);
~RWLock() override;
void LockRead();
void UnLockRead();
void LockWrite();
void UnLockWrite();
private:
bool writeFirst_;
std::thread::id writeThreadID_;
std::atomic_int lockCount_;
std::atomic_uint writeWaitCount_;
};
// RAII封装
template <typename RWLockable>
  class UniqueWriteGuard : NoCopyable {
  public:
  explicit UniqueWriteGuard(RWLockable &rwLockable);
  ~UniqueWriteGuard() override;
  private:
  RWLockable &rwLockable_;
  };
  template <typename RWLockable>
    class UniqueReadGuard : NoCopyable {
    public:
    explicit UniqueReadGuard(RWLockable &rwLockable);
    ~UniqueReadGuard() override;
    private:
    RWLockable &rwLockable_;
    };
2.2.4 安全容器模块
SafeMap 模板类
template <typename K, typename V>
  class SafeMap {
  public:
  SafeMap();
  ~SafeMap();
  SafeMap(const SafeMap& rhs);
  SafeMap& operator=(const SafeMap& rhs);
  // 基本操作
  int Size();
  bool IsEmpty();
  void Clear();
  // 插入操作
  bool Insert(const K& key, const V& value);
  void EnsureInsert(const K& key, const V& value);
  // 查找操作
  bool Find(const K& key, V& value);
  V ReadVal(const K& key);
  bool FindOldAndSetNew(const K& key, V& oldValue, const V& newValue);
  // 删除操作
  void Erase(const K& key);
  // 遍历操作
  void Iterate(const SafeMapCallBack& callback);
  template<typename LambdaCallback>
    void ChangeValueByLambda(const K& key, LambdaCallback callback);
    private:
    mutable std::mutex mutex_;
    std::map<K, V> map_;
      };
SafeBlockQueue 模板类
template <typename T>
  class SafeBlockQueue {
  public:
  explicit SafeBlockQueue(int capacity);
  virtual ~SafeBlockQueue();
  // 阻塞操作
  virtual void Push(T const& elem);
  T Pop();
  // 非阻塞操作
  virtual bool PushNoWait(T const& elem);
  bool PopNotWait(T& outtask);
  // 状态查询
  unsigned int Size();
  bool IsEmpty();
  bool IsFull();
  protected:
  unsigned long maxSize_;
  std::mutex mutexLock_;
  std::condition_variable cvNotEmpty_;
  std::condition_variable cvNotFull_;
  std::queue<T> queueT_;
    };
    // 带任务跟踪的阻塞队列
    template <typename T>
      class SafeBlockQueueTracking : public SafeBlockQueue<T> {
        public:
        explicit SafeBlockQueueTracking(int capacity);
        virtual ~SafeBlockQueueTracking();
        virtual void Push(T const& elem);
        virtual bool PushNoWait(T const& elem);
        bool OneTaskDone();
        void Join();
        int GetUnfinishTaskNum();
        protected:
        std::atomic<int> unfinishedTaskCount_;
          std::condition_variable cvAllTasksDone_;
          };
2.2.5 定时器模块
Timer 类
class Timer {
public:
using TimerCallback = std::function<void()>;
  using TimerCallbackPtr = std::shared_ptr<TimerCallback>;
    explicit Timer(const std::string& name, int timeoutMs = 1000);
    virtual ~Timer();
    // 定时器控制
    virtual uint32_t Setup();
    virtual void Shutdown(bool useJoin = true);
    // 事件管理
    uint32_t Register(const TimerCallback& callback,
    uint32_t interval,
    bool once = false);
    void Unregister(uint32_t timerId);
    private:
    struct TimerEntry {
    uint32_t timerId;
    uint32_t interval;
    TimerCallback callback;
    bool once;
    int timerFd;
    };
    void MainLoop();
    void OnTimer(int timerFd);
    std::string name_;
    int timeoutMs_;
    std::thread thread_;
    EventReactor *reactor_;
    std::map<uint32_t, TimerEntryList> intervalToTimers_;
      std::map<uint32_t, TimerEntryPtr> timerToEntries_;
        std::mutex mutex_;
        };
2.2.6 事件处理模块
IOEventReactor 类
class IOEventReactor {
public:
static constexpr uint8_t FLAG_CHANGED = 0x01;
static constexpr size_t INIT_FD_NUMS = 8;
IOEventReactor();
virtual ~IOEventReactor();
// 生命周期管理
ErrCode SetUp();
ErrCode CleanUp();
ErrCode Clean(int fd);
// 事件处理器管理
ErrCode AddHandler(IOEventHandler* target);
ErrCode RemoveHandler(IOEventHandler* target);
ErrCode UpdateHandler(IOEventHandler* target);
ErrCode FindHandler(IOEventHandler* target);
// 事件循环
void Run(int timeout);
void Terminate();
// 启用/禁用处理
void EnableHandling();
void DisableHandling();
private:
struct FdEvents {
std::shared_ptr<IOEventHandler> head;
  EventId events;
  uint8_t flags;
  };
  std::mutex mutex_;
  std::atomic<bool> loopReady_;
    std::atomic<bool> enabled_;
      std::vector<struct FdEvents> ioHandlers_;
        std::unique_ptr<IOEventEpoll> backend_;
          };
2.2.7 单例模式模块
DelayedSingleton 模板类
template<typename T>
  class DelayedSingleton : public NoCopyable {
  public:
  // 获取单例实例（线程安全，懒加载）
  static std::shared_ptr<T> GetInstance();
    // 销毁单例实例
    static void DestroyInstance();
    private:
    static std::shared_ptr<T> instance_;
      static std::mutex mutex_;
      };
DelayedRefSingleton 模板类
template<typename T>
  class DelayedRefSingleton : public NoCopyable {
  public:
  // 获取单例引用（线程安全，懒加载）
  static T& GetInstance();
  private:
  static T* instance_;
  static std::mutex mutex_;
  };
Singleton 模板类
template<typename T>
  class Singleton : public NoCopyable {
  public:
  // 获取单例引用（饿汉式，程序启动时初始化）
  static T& GetInstance();
  private:
  static T instance_;
  };
2.2.8 观察者模式模块
Observable 类
class Observable {
public:
virtual ~Observable() = default;
// 观察者管理
void AddObserver(const std::shared_ptr<Observer>& o);
  void RemoveObserver(const std::shared_ptr<Observer>& o);
    void RemoveAllObservers();
    // 通知观察者
    void NotifyObservers();
    void NotifyObservers(const ObserverArg* arg);
    // 状态查询
    int GetObserversCount();
    protected:
    bool HasChanged();
    void SetChanged();
    void ClearChanged();
    std::set<std::shared_ptr<Observer>> obs;
      std::mutex mutex_;
      private:
      bool changed_ = false;
      };
Observer 类
class Observer {
public:
virtual ~Observer() = default;
// 更新接口（由Observable调用）
virtual void Update(const Observable* o, const ObserverArg* arg) = 0;
};

2.3 继承与多态

继承关系图
«abstract»
NoCopyable
#NoCopyable()
#~NoCopyable()
RefBase
-RefCounter* refs_
+IncStrongRef()
+DecStrongRef()
+IncWeakRef()
+DecWeakRef()
+OnFirstStrongRef()
+OnLastStrongRef()
+OnLastWeakRef()
Parcelable
+bool asRemote_
+Marshalling() : bool
Ashmem
-int memoryFd_
-int32_t memorySize_
+CreateAshmem() : sptr<Ashmem>
+MapAshmem()
+WriteToAshmem()
+ReadFromAshmem()
RWLock
-bool writeFirst_
-atomic_int lockCount_
+LockRead()
+UnLockRead()
+LockWrite()
+UnLockWrite()
ThreadPool
-vector<thread> threads_
-deque<Task> tasks_
+Start()
+Stop()
+AddTask()
SafeBlockQueue<T>
#unsigned long maxSize_
#queue<T> queueT_
+Push()
+Pop()
SafeBlockQueueTracking<T>
-atomic<int> unfinishedTaskCount_
+OneTaskDone()
+Join()
多态设计说明
基类虚函数设计目的
RefBaseOnFirstStrongRef(), OnLastStrongRef(), OnLastWeakRef()允许子类在引用计数变化时执行自定义逻辑
ParcelableMarshalling()要求子类实现序列化逻辑
ThreadRun(), ReadyToWork()子类实现具体的线程执行逻辑
ObserverUpdate()子类实现具体的更新响应逻辑
AllocatorAlloc(), Dealloc(), Realloc()允许自定义内存分配策略

2.4 类图

智能指针模块类图
持有
创建
继承
管理
持有
相互转换
RefCounter
-atomic<int> atomicStrong_
-atomic<int> atomicWeak_
-atomic<int> atomicRefCount_
-RefPtrCallback callback_
+IncStrongRefCount() : int
+DecStrongRefCount() : int
+IncWeakRefCount() : int
+DecWeakRefCount() : int
+GetStrongRefCount() : int
+GetWeakRefCount() : int
WeakRefCounter
-atomic<int> atomicWeak_
-RefCounter* refCounter_
-void* cookie_
+GetRefPtr()
+IncWeakRefCount()
+DecWeakRefCount()
+AttemptIncStrongRef() : bool
RefBase
-RefCounter* refs_
+IncStrongRef()
+DecStrongRef()
+CreateWeakRef()
+ExtendObjectLifetime()
+OnFirstStrongRef()
+OnLastStrongRef()
sptr<T>
-T* refs_
+MakeSptr() : sptr<T>
+GetRefPtr()
+clear()
+operator*()
+operator->()
wptr<T>
-WeakRefCounter* refs_
+GetRefPtr()
+promote() : sptr<T>
+AttemptIncStrongRef() : bool
Parcelable
+bool asRemote_
+uint8_t behavior_
+Marshalling() : bool
+SetBehavior()
+TestBehavior() : bool
数据容器模块类图
实现
使用
读写
«interface»
Allocator
+Alloc()
+Dealloc()
+Realloc()
DefaultAllocator
+Alloc()
+Dealloc()
+Realloc()
Parcel
-uint8_t* data_
-size_t readCursor_
-size_t writeCursor_
-size_t dataCapacity_
-Allocator* allocator_
+WriteBool() : bool
+WriteInt32() : bool
+WriteString() : bool
+WriteParcelable() : bool
+ReadBool() : bool
+ReadInt32() : int32_t
+ReadString() : string
+ReadParcelable~T~()
Parcelable
+bool asRemote_
+Marshalling() : bool
线程管理模块类图
使用
使用
«abstract»
Thread
-pthread_t thread_
-mutex lock_
-bool exitPending_
-bool running_
+Start() : ThreadStatus
+NotifyExitSync() : ThreadStatus
+NotifyExitAsync()
+IsRunning() : bool
#Run() : bool
ThreadPool
-string myName_
-vector<thread> threads_
-deque<Task> tasks_
-size_t maxTaskNum_
-bool running_
+Start() : uint32_t
+Stop()
+AddTask()
+GetCurTaskNum() : size_t
RWLock
-bool writeFirst_
-atomic_int lockCount_
-atomic_uint writeWaitCount_
+LockRead()
+UnLockRead()
+LockWrite()
+UnLockWrite()
UniqueWriteGuard<RWLockable>
-RWLockable& rwLockable_
+UniqueWriteGuard()
+~UniqueWriteGuard()
UniqueReadGuard<RWLockable>
-RWLockable& rwLockable_
+UniqueReadGuard()
+~UniqueReadGuard()
事件处理模块类图
管理
使用
使用
IOEventReactor
-vector<FdEvents> ioHandlers_
-unique_ptr<IOEventEpoll> backend_
-atomic<bool> loopReady_
+SetUp() : ErrCode
+CleanUp() : ErrCode
+AddHandler() : ErrCode
+RemoveHandler() : ErrCode
+Run()
+Terminate()
IOEventHandler
-int fd_
-EventId events_
-EventCallback callback_
+Start() : ErrCode
+Stop() : ErrCode
+Update() : ErrCode
+GetFd() : int
IOEventEpoll
-int epollFd_
+Add() : ErrCode
+Modify() : ErrCode
+Remove() : ErrCode
+Polling() : int
Timer
-string name_
-int timeoutMs_
-thread thread_
-EventReactor* reactor_
+Setup() : uint32_t
+Shutdown()
+Register() : uint32_t
+Unregister()

2.5 模块内部依赖框图

文件模块
事件模块
容器模块
线程模块
同步模块
核心模块
基础模块
file_ex.h
文件操作
directory_ex.h
目录操作
mapped_file.h
文件映射
ashmem.h
共享内存
io_event_common.h
事件通用
io_event_handler.h
事件处理器
io_event_reactor.h
事件反应器
timer.h
定时器
safe_map.h
安全Map
safe_queue.h
安全队列
safe_block_queue.h
阻塞队列
thread_ex.h
线程类
thread_pool.h
线程池
rwlock.h
读写锁
semaphore_ex.h
信号量
singleton.h
单例模式
refbase.h
智能指针
parcel.h
数据容器
flat_obj.h
平面对象
nocopyable.h
基础宏定义
errors.h
错误码

3. 模块间交互

3.1 交互描述

3.1.1 与IPC/RPC框架的交互

c_utils通过Parcel类为IPC/RPC框架提供数据序列化能力：

  • 数据序列化: 使用Parcel::WriteXxx()方法将数据写入Parcel
  • 数据反序列化: 使用Parcel::ReadXxx()方法从Parcel读取数据
  • 对象传输: 实现Parcelable接口的对象可以通过Parcel进行跨进程传输
  • 远程对象: 通过WriteRemoteObject()/ReadObject()支持远程对象引用
3.1.2 与内核的交互
交互方式说明
epollIOEventReactor使用epoll实现IO事件多路复用
timerfdTimer使用timerfd实现定时器功能
ashmemAshmem类通过/dev/ashmem设备文件操作匿名共享内存
mmapMappedFile使用mmap实现文件内存映射
pthreadThread类封装pthread接口
3.1.3 异步处理与事件驱动

事件驱动模型:

回调
系统层
反应器层
用户层
注册
委托
事件发生
触发
Callback执行
IOEventEpoll
epoll
IOEventReactor
IOEventHandler
3.1.4 多线程处理方式

线程池工作模式:

ThreadPool
调用方
工作线程组
AddTask
取任务
取任务
取任务
任务队列
Thread 1
Thread 2
Thread 3
调用方

3.2 外部依赖框图

graph TB
    subgraph c_utils[c_utils 公共基础库]
        SmartPtr[智能指针]
        Parcel[数据容器]
        Thread[线程管理]
        Timer[定时器]
        Event[事件处理]
        SafeContainer[安全容器]
    end
    subgraph 依赖库
        subgraph STL[C++标准库]
            atomic["<atomic>"]
            thread["<thread>"]
            mutex["<mutex>"]
            cv["<condition_variable>"]
            functional["<functional>"]
            memory["<memory>"]
            containers["<map> <vector> <queue>"]
        end
        subgraph Kernel[Linux内核]
            epoll[epoll]
            timerfd[timerfd]
            ashmem[ashmem]
            mmap[mmap]
            pthread[pthread]
        end
        subgraph Third[第三方库]
            RustFFI[Rust FFI
可选]
        end
    end
    subgraph 被依赖
        IPC[IPC/RPC框架]
        DDS[分布式数据管理]
        Graphics[图形子系统]
    end
    c_utils --> STL
    c_utils --> Kernel
    c_utils -.-> Third
    IPC -->|Parcel/RefBase| c_utils
    DDS -->|sptr/ThreadPool| c_utils
    Graphics -->|Ashmem/RWLock| c_utils

4. 状态机转换图

4.1 智能指针状态机

4.1.1 状态机树图
RefBase对象生命周期
未引用状态
strongCnt=0
weakCnt=0
强引用状态
strongCnt>0
weakCnt>=0
扩展生命周期状态
strongCnt=0
weakCnt>0
extended=true
4.1.2 状态切换规则
当前状态事件/条件目标状态动作
未引用IncStrongRef()强引用调用OnFirstStrongRef()
强引用DecStrongRef() 且 strongCnt=0未引用/销毁调用OnLastStrongRef()，如未扩展则销毁
强引用ExtendObjectLifetime()扩展生命周期设置扩展标志
扩展生命周期DecWeakRef() 且 weakCnt=0销毁调用OnLastWeakRef()并销毁
4.1.3 状态转换图
stateDiagram-v2
    [*] --> Initial: 对象创建
    Initial --> StrongRef: IncStrongRef()
OnFirstStrongRef()
    StrongRef --> StrongRef: DecStrong(cnt>0)
    StrongRef --> Destroyed: DecStrong(cnt=0)
!extended
OnLastStrongRef()
    StrongRef --> Extended: ExtendLifetime()
    Extended --> Destroyed: DecWeak(cnt=0)
OnLastWeakRef()
    Destroyed --> [*]
    state Initial {
        [*] --> Unreferenced
        note right of Unreferenced: strongCnt=0
weakCnt=0
    }
    state StrongRef {
        [*] --> Referenced
        note right of Referenced: strongCnt>0
    }
    state Extended {
        [*] --> ExtendedLife
        note right of ExtendedLife: strongCnt=0
weakCnt>0
extended=true
    }

4.2 线程状态机

4.2.1 状态机树图
Thread生命周期
初始状态
running=false
exitPending=false
运行状态
running=true
exitPending=false
退出等待状态
running=true
exitPending=true
终止状态
running=false
4.2.2 状态转换图
Start()
Run()返回true
NotifyExit()
Run()返回false
Run()返回true
Run()返回false
Created
Running
ExitPending
Terminated
线程未启动
线程执行中
等待退出
线程已终止

4.3 定时器状态机

4.3.1 状态转换图
Setup()
Register()
Timeout(once=false)
Register()新事件
Unregister()所有事件
Shutdown()
Shutdown()
Created
Ready
Active
Shutdown
定时器已创建
就绪，无活动事件
有活动的定时事件
定时器已关闭

4.4 IO事件处理状态机

SetUp()
AddHandler()
Run()
事件处理完成
Terminate()
RemoveHandler()所有
Terminate()
CleanUp()
Created
Ready
Active
Polling
Stopped
Destroyed
反应器已创建
已初始化
有活动Handler
轮询事件中
已停止
已销毁

5. 接口设计

5.1 公共接口

5.1.1 智能指针接口
sptr<T>::MakeSptr()
项目说明
功能创建新对象并返回管理该对象的sptr智能指针（推荐方式）
原型template <typename... Args> static sptr<T> MakeSptr(Args&&... args)
参数args - 传递给T类型构造函数的参数
返回值管理新创建对象的sptr智能指针
异常内存分配失败时抛出std::bad_alloc
线程安全是
wptr<T>::promote()
项目说明
功能将弱引用提升为强引用
原型const sptr<T> promote() const
参数无
返回值成功返回有效sptr，失败返回空sptr
异常无
线程安全是
5.1.2 数据容器接口
Parcel::WriteInt32()
项目说明
功能向Parcel写入32位整数
原型bool WriteInt32(int32_t value)
参数value - 要写入的整数值
返回值成功返回true，失败返回false
异常无
线程安全否（需外部同步）
Parcel::ReadInt32()
项目说明
功能从Parcel读取32位整数
原型int32_t ReadInt32()
参数无
返回值读取的整数值
异常无
线程安全否（需外部同步）
Parcel::WriteParcelable()
项目说明
功能向Parcel写入Parcelable对象
原型bool WriteParcelable(const Parcelable *object)
参数object - 要写入的Parcelable对象指针
返回值成功返回true，失败返回false
异常无
线程安全否（需外部同步）
5.1.3 线程管理接口
ThreadPool::Start()
项目说明
功能启动指定数量的工作线程
原型uint32_t Start(int threadsNum)
参数threadsNum - 要启动的线程数量
返回值成功返回ERR_OK，失败返回错误码
异常无
线程安全是
ThreadPool::AddTask()
项目说明
功能向任务队列添加任务
原型void AddTask(const Task& f)
参数f - 任务函数对象
返回值无
异常无
线程安全是
RWLock::LockRead() / UnLockRead()
项目说明
功能获取/释放读锁
原型void LockRead() / void UnLockRead()
参数无
返回值无
异常无
线程安全是
RWLock::LockWrite() / UnLockWrite()
项目说明
功能获取/释放写锁
原型void LockWrite() / void UnLockWrite()
参数无
返回值无
异常无
线程安全是
5.1.4 定时器接口
Timer::Setup()
项目说明
功能初始化定时器
原型virtual uint32_t Setup()
参数无
返回值成功返回ERR_OK，失败返回错误码
异常无
线程安全否（需在单线程中调用）
Timer::Register()
项目说明
功能注册定时事件
原型uint32_t Register(const TimerCallback& callback, uint32_t interval, bool once = false)
参数callback - 回调函数; interval - 间隔(ms); once - 是否单次
返回值定时器ID
异常无
线程安全是
Timer::Unregister()
项目说明
功能注销定时事件
原型void Unregister(uint32_t timerId)
参数timerId - 要注销的定时器ID
返回值无
异常无
线程安全是
5.1.5 单例模式接口
DelayedSingleton<T>::GetInstance()
项目说明
功能获取单例实例（懒加载，线程安全）
原型static std::shared_ptr<T> GetInstance()
参数无
返回值单例对象的shared_ptr
异常内存分配失败时返回nullptr
线程安全是（双重检查锁定）
DelayedSingleton<T>::DestroyInstance()
项目说明
功能销毁单例实例
原型static void DestroyInstance()
参数无
返回值无
异常无
线程安全是

5.2 数据交换接口

5.2.1 Parcelable接口协议

实现Parcelable接口的类需要：

  1. 继承Parcelable类
  2. 实现Marshalling()虚函数
  3. 实现静态Unmarshalling()函数
class MyData : public Parcelable {
public:
// 序列化：将对象数据写入Parcel
bool Marshalling(Parcel &parcel) const override {
return parcel.WriteInt32(value_) &&
parcel.WriteString(name_);
}
// 反序列化：从Parcel读取数据创建对象
static MyData* Unmarshalling(Parcel &parcel) {
auto data = new MyData();
data->value_ = parcel.ReadInt32();
data->name_ = parcel.ReadString();
return data;
}
private:
int32_t value_;
std::string name_;
};
5.2.2 Observer接口协议
class MyObserver : public Observer {
public:
// 当被观察对象状态改变时调用
void Update(const Observable* o, const ObserverArg* arg) override {
// 处理更新通知
if (arg != nullptr) {
// 使用arg中的数据
}
}
};
// 使用示例
auto observer = std::make_shared<MyObserver>();
  observable->AddObserver(observer);
  observable->SetChanged();
  observable->NotifyObservers(&arg);

5.3 接口调用时序图

5.3.1 智能指针使用时序
调用方 sptr RefBase RefCounter MakeSptr<T>() new T() new RefCounter() 返回 返回对象 IncStrongRef() IncStrongRefCount() 返回计数 OnFirstStrongRef() 返回sptr 使用对象... ~sptr() DecStrongRef() DecStrongRefCount() 返回计数(0) OnLastStrongRef() delete this 调用方 sptr RefBase RefCounter
5.3.2 线程池任务执行时序
调用方 ThreadPool 任务队列 工作线程 Start(n) 创建n个工作线程 线程就绪 AddTask(task) push(task) notify_one() pop() 返回task 执行task() Stop() running_ = false notify_all() join() 线程退出 调用方 ThreadPool 任务队列 工作线程
5.3.3 定时器事件处理时序
调用方 Timer EventReactor timerfd Setup() SetUp() 启动事件循环线程 返回 Register(cb, 1000) timerfd_create() 返回fd timerfd_settime() AddHandler() 返回timerId 等待1000ms... epoll_wait() 超时事件 OnTimer() callback() Shutdown() CleanUp() 返回 调用方 Timer EventReactor timerfd
5.3.4 观察者模式通知时序
调用方 Observable Observer1 Observer2 AddObserver(o1) obs.insert(o1) 返回 AddObserver(o2) obs.insert(o2) 返回 SetChanged() changed_ = true 返回 NotifyObservers(arg) Update(this, arg) 处理完成 Update(this, arg) 处理完成 changed_ = false 返回 调用方 Observable Observer1 Observer2

附录

A. 错误码定义

错误码名称说明
0ERR_OK操作成功
BASE_ERR_OFFSET + ENOMEMERR_NO_MEMORY内存不足
BASE_ERR_OFFSET + ENOSYSERR_INVALID_OPERATION无效操作
BASE_ERR_OFFSET + EINVALERR_INVALID_VALUE无效参数
BASE_ERR_OFFSET + ENOENTERR_NAME_NOT_FOUND名称未找到
BASE_ERR_OFFSET + EPERMERR_PERMISSION_DENIED权限拒绝
BASE_ERR_OFFSET + ENODEVERR_NO_INIT未初始化
BASE_ERR_OFFSET + EEXISTERR_ALREADY_EXISTS已存在
BASE_ERR_OFFSET + EPIPEERR_DEAD_OBJECT对象已销毁
BASE_ERR_OFFSET + EOVERFLOWERR_OVERFLOW溢出
BASE_ERR_OFFSET + ETIMEDOUTERR_TIMED_OUT超时

B. 使用宏定义

宏说明
DISALLOW_COPY_AND_MOVE(className)禁止类的拷贝和移动
DISALLOW_COPY(className)禁止类的拷贝
DISALLOW_MOVE(className)禁止类的移动
DECLARE_DELAYED_SINGLETON(MyClass)声明延迟单例
DECLARE_DELAYED_REF_SINGLETON(MyClass)声明延迟引用单例
DECLARE_SINGLETON(MyClass)声明普通单例
posted @ 2026-01-08 15:13  yangykaifa  阅读(11)  评论(0)    收藏  举报