AIO

A promise-based asynchronous library implemented in C++17
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Build
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Wrap libevent with promise, asynchronize basic components such as timer, based on bufferevent and libcurl implement network asynchronous api, and provide channel to send and receive data between tasks.

(back to top)

Built With

• 
• 
• 

(back to top)

Getting Started

Due to many dependencies, it is not recommended to install manually, you should use vcpkg.

Prerequisites

Create a CMake project and two configuration files, vcpkg-configuration.json and vcpkg.json.

• CMakeLists.txt

  find_package(aio CONFIG REQUIRED)
  add_executable(demo main.cpp)
  target_link_libraries(demo PRIVATE aio::aio)

• vcpkg-configuration.json

  {
    "registries": [
      {
        "kind": "git",
        "repository": "https://github.com/Hackerl/vcpkg-registry",
        "baseline": "891208f06ff08441853ffed299cb298f1df3c25e",
        "packages": [
          "aio",
          "zero"
        ]
      }
    ]
  }

• vcpkg.json

  {
    "name": "demo",
    "version-string": "1.0.0",
    "builtin-baseline": "69efe9cc2df0015f0bb2d37d55acde4a75c9a25b",
    "dependencies": [
      {
        "name": "aio",
        "version>=": "1.0.5"
      },
      {
        "name": "curl",
        "default-features": false
      }
    ]
  }

Export environment variables:

• VCPKG_INSTALLATION_ROOT
• ANDROID_NDK_HOME(Android)

Build

• Linux

  mkdir -p build && cmake -B build -DCMAKE_TOOLCHAIN_FILE="${VCPKG_INSTALLATION_ROOT}/scripts/buildsystems/vcpkg.cmake" && cmake --build build -j$(nproc)

• Android

  # set "ANDROID_PLATFORM" for dependencies installed by vcpkg: echo 'set(VCPKG_CMAKE_SYSTEM_VERSION 24)' >> "${VCPKG_INSTALLATION_ROOT}/triplets/community/arm64-android.cmake"
  mkdir -p build && cmake -B build -DCMAKE_TOOLCHAIN_FILE="${VCPKG_INSTALLATION_ROOT}/scripts/buildsystems/vcpkg.cmake" -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE="${ANDROID_NDK_HOME}/build/cmake/android.toolchain.cmake" -DVCPKG_TARGET_TRIPLET=arm64-android -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-24 && cmake --build build -j$(nproc)

• Windows(Developer PowerShell)

  mkdir -p build && cmake -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_INSTALLATION_ROOT/scripts/buildsystems/vcpkg.cmake" && cmake --build build -j $env:NUMBER_OF_PROCESSORS

(back to top)

Usage

HTTP Requests

• Basic

  #include <aio/http/request.h>
  #include <zero/log.h>
  
  int main() {
      INIT_CONSOLE_LOG(zero::INFO_LEVEL);
  
  #ifdef _WIN32
      WSADATA wsaData;
  
      if (WSAStartup(MAKEWORD(2, 2), &wsaData) != 0) {
          LOG_ERROR("WSAStartup failed");
          return -1;
      }
  #endif
  
      std::shared_ptr<aio::Context> context = aio::newContext();
  
      if (!context)
          return -1;
  
      zero::ptr::RefPtr<aio::http::Requests> requests = zero::ptr::makeRef<aio::http::Requests>(context);
  
      requests->get("https://www.google.com")->then([=](const zero::ptr::RefPtr<aio::http::Response> &response) {
          return response->string();
      })->then([](const std::string &content) {
          LOG_INFO("content: %s", content.c_str());
      })->fail([](const zero::async::promise::Reason &reason) {
          LOG_ERROR("%s", reason.message.c_str());
      })->finally([=]() {
          context->loopBreak();
      });
  
      context->dispatch();
  
  #ifdef _WIN32
      WSACleanup();
  #endif
  
      return 0;
  }

• Post form

  requests->post(
          "https://www.google.com",
          std::map<std::string, std::string>{
                  {"name", "jack"}
          }
  );

• Post file

  requests->post(
          "https://www.google.com",
          std::map<std::string, std::filesystem::path>{
                  {"file", "/tmp/test"}
          }
  );
  
  requests->post(
          "https://www.google.com",
          std::map<std::string, std::variant<std::string, std::filesystem::path>>{
                  {"name", std::string{"jack"}},
                  {"file", std::filesystem::path{"/tmp/test"}}
          }
  );

• Post json

  requests->post(
          "https://www.google.com",
          nlohmann::json{
                  {"name", "jack"}
          }
  )->then([=](const zero::ptr::RefPtr<aio::http::Response> &response) {
      return response->json();
  })->then([](const nlohmann::json &j) {
  
  });
  
  requests->post(
          "https://www.google.com",
          nlohmann::json{
                  {"name", "jack"}
          }
  )->then([=](const zero::ptr::RefPtr<aio::http::Response> &response) {
      return response->json<People>();
  })->then([](const People &people) {
  
  });

• Websocket

  aio::http::ws::connect(context, url)->then([](const zero::ptr::RefPtr<aio::http::ws::WebSocket> &ws) {
      return zero::async::promise::loop<void>([=](const auto &loop) {
          ws->read()->then([=](const aio::http::ws::Message &message) {
              switch (message.opcode) {
                  case aio::http::ws::TEXT:
                      LOG_INFO("receive text message: %s", std::get<std::string>(message.data).c_str());
                      break;
  
                  case aio::http::ws::BINARY: {
                      const auto &binary = std::get<std::vector<std::byte>>(message.data);
                      LOG_INFO(
                              "receive binary message: %s",
                              zero::encoding::hex::encode(binary).c_str()
                      );
                      break;
                  }
  
                  default:
                      break;
              }
  
              return ws->write(message);
          })->then([=]() {
              P_CONTINUE(loop);
          }, [=](const zero::async::promise::Reason &reason) {
              P_BREAK_E(loop, reason);
          });
      });
  })

TCP/TLS

• Basic

  aio::net::stream::connect(context, "www.google.com", 80)->then([=](const zero::ptr::RefPtr<aio::net::stream::IBuffer> &buffer) {
      buffer->writeLine("hello world");
      return buffer->drain()->then([=]() {
          return buffer->read(1024);
      });
  })->then([](nonstd::span<const std::byte> data) {
  
  });

• TLS

  aio::net::ssl::stream::connect(context, "www.google.com", 443)->then([=](const zero::ptr::RefPtr<aio::net::stream::IBuffer> &buffer) {
      buffer->writeLine("hello world");
      return buffer->drain()->then([=]() {
          return buffer->read(1024);
      });
  })->then([](nonstd::span<const std::byte> data) {
  
  });

Worker

• Basic

  aio::toThread<int>(context, []() {
      std::this_thread::sleep_for(100ms);
      return 1024;
  })->then([=](int result) {
      REQUIRE(result == 1024);
  });

• Throw error

  aio::toThread<int>(context, []() -> nonstd::expected<int, zero::async::promise::Reason> {
      std::this_thread::sleep_for(100ms);
      return nonstd::make_unexpected(zero::async::promise::Reason{-1});
  })->then([=](int) {
      FAIL();
  }, [=](const zero::async::promise::Reason &reason) {
      REQUIRE(reason.code == -1);
      context->loopBreak();
  });

Channel

• Basic

  zero::ptr::RefPtr<aio::IChannel<int>> channel = zero::ptr::makeRef<aio::Channel<int, 100>>(context);
  
  zero::async::promise::all(
          zero::ptr::makeRef<aio::ev::Timer>(context)->setInterval(5s, [=]() {
              channel->trySend(1024);
              return true;
          }),
          aio::toThread<void>(context, [=]() {
              while (true) {
                  nonstd::expected<int, aio::Error> result = channel->receiveSync();
  
                  if (!result)
                      break;
  
                  // do something that takes a long time
              }
          })
  );

For more examples, please refer to the Documentation

(back to top)

Roadmap

• Asynchronous Filesystem
  • Linux AIO
  • Windows IOCP
  • POSIX AIO

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

(back to top)

Contact

Hackerl - @Hackerl - patteliu@gmail.com

Project Link: https://github.com/Hackerl/aio

(back to top)

Acknowledgments

• libevent
• libcurl
• nlohmann-json

(back to top)