Android native开发：system/core/base

1. chrono_utils.h

跨平台，为Linux和Win/Darwin提供不同实现。

class boot_clock;
class Timer;

2. cmsg.h

Linux提供cmsg(3)系列宏管理local socket相关的control message。
对cmsg的封装，避免易发错误。

ssize_t SendFileDescriptorVector(borrowed_fd sock, const void* data, size_t len,
                                 const std::vector<int>& fds);
ssize_t ReceiveFileDescriptorVector(borrowed_fd sock, void* data, size_t len, size_t max_fds,
                                    std::vector<android::base::unique_fd>* fds);

template <typename... Args>
ssize_t SendFileDescriptors(borrowed_fd sock, const void* data, size_t len, Args&&... sent_fds);

template <typename... Args>
ssize_t ReceiveFileDescriptors(borrowed_fd sock, void* data, size_t len, Args&&... received_fds);

3. collections.h

辅助函数，把模板的变长参数放入集合容器中。

// Use as follows:
   template <typename... Args>
   std::vector<int> CreateVector(Args&&... args) {
    
    
     std::vector<int> result;
     Append(result, std::forward<Args>(args)...);
     return result;
   }

template <typename CollectionType, typename T>
void Append(CollectionType& collection, T&& arg);

template <typename CollectionType, typename T, typename... Args>
void Append(CollectionType& collection, T&& arg, Args&&... args);

template <typename T, typename Arg, typename... Args>
void AssertType(Arg&&);

template <typename T, typename Arg, typename... Args>
void AssertType(Arg&&, Args&&... args);

4. endian.h

一些宏定义，对函数__builtin_bswap16/32/64的封装。
和标准C库 <sys/endian.h>等价的跨平台实现。

5. errno_restorer.h

临时保存errno，作用域结束后恢复。

class ErrnoRestorer {
    
    
 public:
  ErrnoRestorer() : saved_errno_(errno) {
    
    }
  ~ErrnoRestorer() {
    
     errno = saved_errno_; }
 private:
  const int saved_errno_;
};

6. errors.h

跨平台支持错误码转字符串，Linux上调用strerror。

std::string SystemErrorCodeToString(int error_code);

7. expected.h

实现std::expected。
当std::expected正式进入c++标准后，删除此实现，android::base::expected仅作为std::expected别名。

using android::base::expected;
using android::base::unexpected;

expected<double,std::string> safe_divide(double i, double j) {
    
    
  if (j == 0) return unexpected("divide by zero");
  else return i / j;
}

void test() {
    
    
  auto q = safe_divide(10, 0);
  if (q) {
    
     printf("%f\n", q.value()); }
  else {
    
     printf("%s\n", q.error().c_str()); }
}

8. file.h

文件操作的辅助函数。

class TemporaryFile;

class TemporaryDir;

bool ReadFdToString(borrowed_fd fd, std::string* content);
bool ReadFileToString(const std::string& path, std::string* content,
                      bool follow_symlinks = false);

bool WriteStringToFile(const std::string& content, const std::string& path,
                       bool follow_symlinks = false);
bool WriteStringToFd(const std::string& content, borrowed_fd fd);

bool WriteStringToFile(const std::string& content, const std::string& path,
                       mode_t mode, uid_t owner, gid_t group,
                       bool follow_symlinks = false);

bool ReadFully(borrowed_fd fd, void* data, size_t byte_count);

bool ReadFullyAtOffset(borrowed_fd fd, void* data, size_t byte_count, off64_t offset);
bool WriteFully(borrowed_fd fd, const void* data, size_t byte_count);

bool RemoveFileIfExists(const std::string& path, std::string* err = nullptr);

bool Realpath(const std::string& path, std::string* result);
bool Readlink(const std::string& path, std::string* result);

std::string GetExecutablePath();
std::string GetExecutableDirectory();

std::string Basename(const std::string& path);
std::string Dirname(const std::string& path);

9. format.h

通过这个头文件，可以引入fmtlib库。这个库是静态链接到libbase中的。
下面是一些使用的例子，在Android native代码中实测可用。

// We include fmtlib here as an alias, since libbase will have fmtlib statically linked already.
// It is accessed through its normal fmt:: namespace.

#include <android-base/format.h>

std::string msg = fmt::format("hello {} by fmt", "world");

std::string message = fmt::sprintf("The answer is %d", 42);
fmt::fprintf(stderr, "Don't %s!", "panic");
fmt::printf("Elapsed time: %.2f seconds", 1.23);

std::vector<int> v = {
    
    1, 2, 3};
fmt::print("{}", fmt::join(v, ", "));
// Output: "1, 2, 3"

std::string answer = fmt::to_string(42);

std::vector<char> out;
fmt::format_to(std::back_inserter(out), "{}", 42);

// User-defined literal equivalent of :func:`fmt::format`.
using namespace fmt::literals;
std::string message = "The answer is {}"_format(42);
fmt::print("Elapsed time: {s:.2f} seconds", "s"_a=1.23);

// Constructs a compile-time format string.
// A compile-time error because 'd' is an invalid specifier for strings.
std::string s = format(FMT_STRING("{:d}"), "foo");

10. logging.h

C++ stream接口封装的log。
Android输出到logcat，host上输出到stderr。可用SetLogger设置输出。
默认使用进程名作tag，也可定义宏LOG_TAG（需要在include这个头文件前）。

还提供一些assertion宏。CHECK, CHECK_EQ

// To log:
LOG(INFO) << "Some text; " << some_value;

PLOG(ERROR) << "Write failed"; // 类似perror()
// `Write failed: I/O error`.

CHECK(must_be_true);
CHECK_EQ(a, b) << z_is_interesting_too;

// Log to the kernel log (dmesg).
void KernelLogger(LogId, LogSeverity, const char*, const char*, unsigned int, const char*);
// Log to stderr in the full logcat format (with pid/tid/time/tag details).
void StderrLogger(LogId, LogSeverity, const char*, const char*, unsigned int, const char*);
// Log just the message to stdout/stderr (without pid/tid/time/tag details).
// Useful for replacing printf(3)/perror(3)/err(3)/error(3) in command-line tools.
void StdioLogger(LogId, LogSeverity, const char*, const char*, unsigned int, const char*);

void DefaultAborter(const char* abort_message);
void SetDefaultTag(const std::string& tag);

void InitLogging(char* argv[],
                 LogFunction&& logger = INIT_LOGGING_DEFAULT_LOGGER,
                 AbortFunction&& aborter = DefaultAborter);

// Replace the current logger.
void SetLogger(LogFunction&& logger);
// Replace the current aborter.
void SetAborter(AbortFunction&& aborter);

11. macros.h

几个宏定义。

#define TEMP_FAILURE_RETRY(exp)            
#define DISALLOW_COPY_AND_ASSIGN(TypeName)
#define DISALLOW_IMPLICIT_CONSTRUCTORS(TypeName)

#define arraysize(array) (sizeof(ArraySizeHelper(array)))
#define SIZEOF_MEMBER(t, f) sizeof(std::declval<t>().f)

#define LIKELY( exp )       (__builtin_expect( (exp) != 0, true  ))
#define UNLIKELY( exp )     (__builtin_expect( (exp) != 0, false ))

#define WARN_UNUSED __attribute__((warn_unused_result))

#define ATTRIBUTE_UNUSED __attribute__((__unused__))
#define FALLTHROUGH_INTENDED [[clang::fallthrough]]  // NOLINT

12. mapped_file.h

提供filemapping跨平台实现。

class MappedFile {
    
    
 public:
  static std::unique_ptr<MappedFile> FromFd(borrowed_fd fd, off64_t offset, size_t length,
  static std::unique_ptr<MappedFile> FromOsHandle(os_handle h, off64_t offset, size_t length,
                                                  int prot);
  MappedFile(MappedFile&& other);
  MappedFile& operator=(MappedFile&& other);

  char* data() const {
    
     return base_ + offset_; }
  size_t size() const {
    
     return size_; }

 private:
  MappedFile(char* base, size_t size, size_t offset) : base_(base), size_(size), offset_(offset) {
    
    }
};

13. memory.h

2个memcpy辅助函数。

// Use memcpy for access to unaligned data on targets with alignment
// restrictions.  The compiler will generate appropriate code to access these
// structures without generating alignment exceptions.
template <typename T>
static inline T get_unaligned(const void* address) {
    
    
  T result;
  memcpy(&result, address, sizeof(T));
  return result;
}

template <typename T>
static inline void put_unaligned(void* address, T v) {
    
    
  memcpy(address, &v, sizeof(T));
}

14. no_destructor.h

TODO：没太理解这个类的目的是啥？？
使用placement new在栈空间上初始化类型T的对象。

template <typename T>
class NoDestructor;

15. off64_t.h

/** Mac OS has always had a 64-bit off_t, so it doesn't have off64_t. */
typedef off_t off64_t;

16. parsebool.h

把string解析成bool类型（ParseBoolResult封装）。

ParseBoolResult ParseBool(std::string_view s);

17. parsedouble.h

把string解析成double类型。
TODO：都是static函数？外部不能调用？

template <typename T, T (*strtox)(const char* str, char** endptr)>
static inline bool ParseFloatingPoint(const char* s, T* out, T min, T max);

static inline bool ParseDouble(const char* s, double* out,
                               double min = std::numeric_limits<double>::lowest(),
                               double max = std::numeric_limits<double>::max());

static inline bool ParseDouble(const std::string& s, double* out,
                               double min = std::numeric_limits<double>::lowest(),
                               double max = std::numeric_limits<double>::max());

static inline bool ParseFloat(const char* s, float* out,
                              float min = std::numeric_limits<float>::lowest(),
                              float max = std::numeric_limits<float>::max());

static inline bool ParseFloat(const std::string& s, float* out,
                              float min = std::numeric_limits<float>::lowest(),
                              float max = std::numeric_limits<float>::max());

18. parseint.h

string解析int辅助函数。

template <typename T>
bool ParseUint(const char* s, T* out, T max = std::numeric_limits<T>::max(),
               bool allow_suffixes = false);

template <typename T>
bool ParseUint(const std::string& s, T* out, T max = std::numeric_limits<T>::max(),
               bool allow_suffixes = false);

template <typename T>
bool ParseByteCount(const char* s, T* out, T max = std::numeric_limits<T>::max());

template <typename T>
bool ParseByteCount(const std::string& s, T* out, T max = std::numeric_limits<T>::max());

template <typename T>
bool ParseInt(const char* s, T* out,
              T min = std::numeric_limits<T>::min(),
              T max = std::numeric_limits<T>::max())

template <typename T>
bool ParseInt(const std::string& s, T* out,
              T min = std::numeric_limits<T>::min(),
              T max = std::numeric_limits<T>::max());

19. parsenetaddress.h

string解析网络地址辅助函数。

bool ParseNetAddress(const std::string& address, std::string* host, int* port,
                     std::string* canonical_address, std::string* error);

20. process.h

遍历/proc目录获取所有pid。

class AllPids {
    
    
  class PidIterator {
    
    
   public:
    PidIterator(DIR* dir) : dir_(dir, closedir) {
    
     Increment(); }
    PidIterator& operator++();
  };

 public:
  PidIterator begin() {
    
     return opendir("/proc"); }
  PidIterator end() {
    
     return nullptr; }
};

21. properties.h

封装读写property接口。

std::string GetProperty(const std::string& key, const std::string& default_value);

bool GetBoolProperty(const std::string& key, bool default_value);

template <typename T> T GetIntProperty(const std::string& key,
                                       T default_value,
                                       T min = std::numeric_limits<T>::min(),
                                       T max = std::numeric_limits<T>::max());

template <typename T> T GetUintProperty(const std::string& key,
                                        T default_value,
                                        T max = std::numeric_limits<T>::max());

bool SetProperty(const std::string& key, const std::string& value);

bool WaitForProperty(const std::string& key, const std::string& expected_value,
                     std::chrono::milliseconds relative_timeout = std::chrono::milliseconds::max());

bool WaitForPropertyCreation(const std::string& key, std::chrono::milliseconds relative_timeout =
                                                         std::chrono::milliseconds::max());

// Cached system property lookup. For code that needs to read the same property multiple times,
// this class helps optimize those lookups.
class CachedProperty;

22. result.h

1）Result<T>包含一个类型T的值（类似optional<T>访问），或者包含类型ResultError的错误信息（通过Result<T>::error()访问）
2）ResultError包含一个string类型的信息和errno，且可直接用ostream输出。
3）ResultError<void>用于没有返回值的函数，函数成功返回，return { }。
4）返回的ResultError<T>，可以通过返回类型T对象，或者任何可以转换为T类型的对象，自动构建ResultError。
5）Error 和 ErrnoError用于创建出错时的Result<T>，Errorf 和 ErrnoErrorf格式化输出错误信息。
6）ResultError类型可以直接构建Result<T>, Result<U>.error() -> Result<T>

Result<U> CalculateResult(const T& input) {
    
    
  U output;
  if (!SomeOtherCppFunction(input, &output)) {
    
    
    return Errorf("SomeOtherCppFunction {} failed", input);
  }
  if (!c_api_function(output)) {
    
    
    return ErrnoErrorf("c_api_function {} failed", output);
  }
  return output;
}

auto output = CalculateResult(input);
if (!output) return Error() << "CalculateResult failed: " << output.error();
UseOutput(*output);

23. scopeguard.h

提供一个RAII辅助类，确保在作用域结束时调用指定的函数（对象）。

// ScopeGuard ensures that the specified functor is executed no matter how the
// current scope exits.
template <typename F>
class ScopeGuard {
    
    
 public:
  ScopeGuard(F&& f) : f_(std::forward<F>(f)), active_(true) {
    
    }

  ScopeGuard(ScopeGuard&& that) noexcept : f_(std::move(that.f_)), active_(that.active_) {
    
    
    that.active_ = false;
  }

  template <typename Functor>
  ScopeGuard(ScopeGuard<Functor>&& that) : f_(std::move(that.f_)), active_(that.active_) {
    
    
    that.active_ = false;
  }

  ~ScopeGuard() {
    
    
    if (active_) f_();
  }

  private:
  template <typename Functor>
  friend class ScopeGuard;

  F f_;
  bool active_;
};

template <typename F>
ScopeGuard<F> make_scope_guard(F&& f) {
    
    
  return ScopeGuard<F>(std::forward<F>(f));
}

24. stringprintf.h

通过类似printf函数格式，拼接字符串的辅助函数。
可以用libfmt替代。

std::string StringPrintf(const char* fmt, ...);
void StringAppendF(std::string* dst, const char* fmt, ...);
void StringAppendV(std::string* dst, const char* format, va_list ap);

25. strings.h

string操作辅助函数，部分可以用std::string的标准库函数替代。

std::vector<std::string> Split(const std::string& s,
                               const std::string& delimiters);

std::string Trim(const std::string& s);

template <typename ContainerT, typename SeparatorT>
std::string Join(const ContainerT& things, SeparatorT separator);

// We instantiate the common cases in strings.cpp.
extern template std::string Join(const std::vector<std::string>&, char);
extern template std::string Join(const std::vector<const char*>&, char);
extern template std::string Join(const std::vector<std::string>&, const std::string&);
extern template std::string Join(const std::vector<const char*>&, const std::string&);

bool StartsWith(std::string_view s, std::string_view prefix);
bool StartsWith(std::string_view s, char prefix);
bool StartsWithIgnoreCase(std::string_view s, std::string_view prefix);

bool EndsWith(std::string_view s, std::string_view suffix);
bool EndsWith(std::string_view s, char suffix);
bool EndsWithIgnoreCase(std::string_view s, std::string_view suffix);

bool EqualsIgnoreCase(std::string_view lhs, std::string_view rhs);

// Removes `prefix` from the start of the given string and returns true (if
// it was present), false otherwise.
inline bool ConsumePrefix(std::string_view* s, std::string_view prefix);

// Removes `suffix` from the end of the given string and returns true (if
// it was present), false otherwise.
inline bool ConsumeSuffix(std::string_view* s, std::string_view suffix);

// Replaces `from` with `to` in `s`, once if `all == false`, or as many times as
// there are matches if `all == true`.
[[nodiscard]] std::string StringReplace(std::string_view s, std::string_view from,
                                        std::string_view to, bool all);

26. test_utils.h

gtest辅助类和宏。
assert_和expect_宏是对std::regex_search和gtest宏封装。

class CapturedStdFd；

#define ASSERT_MATCH(str, pattern);
#define ASSERT_NOT_MATCH(str, pattern);
#define EXPECT_MATCH(str, pattern);
#define EXPECT_NOT_MATCH(str, pattern);

27. thread_annotations.h

#define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))

#define CAPABILITY(x) \
      THREAD_ANNOTATION_ATTRIBUTE__(capability(x))

#define SCOPED_CAPABILITY \
      THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)

#define SHARED_CAPABILITY(...) \
      THREAD_ANNOTATION_ATTRIBUTE__(shared_capability(__VA_ARGS__))

#define GUARDED_BY(x) \
      THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))

#define EXCLUSIVE_LOCKS_REQUIRED(...) \
      THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))

#define SHARED_LOCKS_REQUIRED(...) \
      THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))

#define ACQUIRED_BEFORE(...) \
      THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))
...

1）一些thread相关的__attribute__宏定义。
2）ScopedLockAssertion，为了Clang做线程安全分析的辅助类。

28. threads.h

跨平台支持获取thread id，在Linux上调用gettid()或syscall(__NR_gettid)

uint64_t GetThreadId();

29. unique_fd.h

封装fd的RAII类，提供unique_fd和borrowed_fd。

// 有bug的代码
     int print(int fd) {
    
    
         int rc;
         char buf[128];
         while ((rc = read(fd, buf, sizeof(buf))) > 0) {
    
    
             printf("%.*s", rc);
         }
         close(fd);
     }

     int bug() {
    
    
         FILE* f = fopen("foo", "r");
         print(fileno(f));
         fclose(f); // print中还在使用文件，外面把文件close了
     }

// Container for a file descriptor that automatically closes the descriptor as
// it goes out of scope.
//
      unique_fd ufd(open("/some/path", "r"));
      if (ufd.get() == -1) return error;
      // Do something useful, possibly including 'return'.
      return 0; // Descriptor is closed for you.


inline FILE* Fdopen(unique_fd&& ufd, const char* mode) {
    
    
inline DIR* Fdopendir(unique_fd&& ufd) {
    
    
template <typename T>
int close(const android::base::unique_fd_impl<T>&);
template <typename T>
FILE* fdopen(const android::base::unique_fd_impl<T>&, const char* mode);
template <typename T>
DIR* fdopendir(const android::base::unique_fd_impl<T>&);

30. utf8.h

Windows平台上UTF和wchar相互转换的函数。