PhotonLibOS

https://photonlibos.github.io/docs/
Admin
PhotonLibOS is a high-performance C++ coroutine library designed to provide a fast, symmetric...
Tokens:17,681
Snippets:199
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install build dependencies

Source: https://photonlibos.github.io/docs/introduction/how-to-build

Install required system packages for building PhotonLibOS on different platforms.

```bash
dnf install git gcc-c++ cmake  
dnf install openssl-devel libcurl-devel libaio-devel zlib-devel  
```

```bash
apt install git cmake  
apt install libssl-dev libcurl4-openssl-dev libaio-dev zlib1g-dev  
```

```bash
brew install cmake openssl@1.1 pkg-config  
```

--------------------------------

### Build and run tests

Source: https://photonlibos.github.io/docs/introduction/how-to-build

Install testing dependencies and execute the test suite using ctest.

```bash
# Install additional dependencies  
# Note that for the latest RHEL-like OS, libgsasl-devel has changed to cyrus-sasl-devel  
dnf install epel-release  
dnf config-manager --set-enabled powertools  
dnf install gtest-devel gmock-devel gflags-devel fuse-devel libgsasl-devel nasm  
  
# Build examples and test code  
cmake -B build -D PHOTON_BUILD_TESTING=ON  
cmake --build build -j 8  
  
# Run all test cases  
cd build  
ctest  
```

```bash
# Install additional dependencies  
apt install libgtest-dev libgmock-dev libgflags-dev libfuse-dev libgsasl7-dev nasm  
  
# Build examples and test code  
cmake -B build -D PHOTON_BUILD_TESTING=ON  
cmake --build build -j 8  
  
# Run all test cases  
cd build  
ctest  
```

```bash
# Install additional dependencies  
brew install gflags googletest gsasl nasm  
  
# Build examples and test code  
cmake -B build -D OPENSSL_ROOT_DIR=/usr/local/opt/openssl@1.1 -D PHOTON_BUILD_TESTING=ON  
cmake --build build -j 8  
  
# Run all test cases  
cd build  
ctest  
```

--------------------------------

### Example of creating multiple threads

Source: https://photonlibos.github.io/docs/api/thread

Demonstrates creating 2000 sleeping coroutines using thread_create11.

```cpp
int main() {  
    photon::init();  
    for (int i = 0; i < 2000; ++i) {  
        photon::thread_create11([]{  
            photon::thread_usleep(-1UL);  
        });  
    }  
    photon::thread_usleep(-1UL);  
}  
```

--------------------------------

### Usage of thread_create11 with global functions

Source: https://photonlibos.github.io/docs/api/thread

Example of creating a thread from a global function.

```cpp
double func(int a, char b);  
  
auto th = photon::thread_create11(func, 1, '2');  
```

--------------------------------

### Declare Delegate Type

Source: https://photonlibos.github.io/docs/api/delegate_callback

Example of creating a specific delegate type for a file opening operation.

```cpp
class File;  
  
using OpenCallback = Delegate<File*, const std::string&, const char*> ;
```

--------------------------------

### Usage of thread_create11 with functors

Source: https://photonlibos.github.io/docs/api/thread

Example of creating a thread from a lambda or function object.

```cpp
int a = 1; char b = '2';  
  
auto th = photon::thread_create11([&] {  
    // Access a and b  
});  
```

--------------------------------

### Usage of thread_create11 with member functions

Source: https://photonlibos.github.io/docs/api/thread

Example of creating a thread from a class member function.

```cpp
class A {  
    void func(int a, char b);  
  
    void run() {  
        photon::thread_create11(&A::func, this, 1, '2');  
    }  
};  
```

--------------------------------

### WorkPool Async Call

Source: https://photonlibos.github.io/docs/api/vcpu-and-multicore

Methods for asynchronous task execution and usage examples within a WorkPool.

```cpp
template <typename Task>  
int WorkPool::async_call(Task* task);  
```

```cpp
photon::WorkPool pool(4, photon::INIT_EVENT_DEFAULT, photon::INIT_IO_NONE, 32768);  
photon::semephore sem;  
  
pool.async_call(new auto ([&]{  
    photon::thread_sleep(1);  
    sem.signal(1);  
}));  
```

--------------------------------

### Initialize and terminate Photon WorkPool

Source: https://photonlibos.github.io/docs/api/std-compatible-api

Demonstrates the initialization and cleanup of the Photon environment and the global WorkPool.

```cpp
int main() {  
    photon::init(event_engine, io_engine);  
    DEFER(photon::fini());  
  
    photon_std::work_pool_init(8, event_engine, io_engine);  
    DEFER(photon_std::work_pool_fini());  
}  
```

--------------------------------

### Initialize Photon with libcurl

Source: https://photonlibos.github.io/docs/api/network

Required initialization step to enable libcurl as an IO_ENGINE.

```cpp
photon::init(INIT_EVENT_DEFAULT, INIT_IO_LIBCURL);  
```

--------------------------------

### Configure static build with third-party dependencies

Source: https://photonlibos.github.io/docs/introduction/how-to-build

Build all dependencies from source to create a portable binary.

```bash
cmake -B build -D CMAKE_BUILD_TYPE=RelWithDebInfo \
-D PHOTON_BUILD_TESTING=ON \
-D PHOTON_BUILD_DEPENDENCIES=ON \
-D PHOTON_ENABLE_URING=ON \
-D PHOTON_AIO_SOURCE=https://pagure.io/libaio/archive/libaio-0.3.113/libaio-0.3.113.tar.gz \
-D PHOTON_ZLIB_SOURCE=https://github.com/madler/zlib/releases/download/v1.2.13/zlib-1.2.13.tar.gz \
-D PHOTON_URING_SOURCE=https://github.com/axboe/liburing/archive/refs/tags/liburing-2.3.tar.gz \
-D PHOTON_CURL_SOURCE=https://github.com/curl/curl/releases/download/curl-7_88_1/curl-7.88.1.tar.gz \
-D PHOTON_OPENSSL_SOURCE=https://github.com/openssl/openssl/releases/download/OpenSSL_1_1_1w/openssl-1.1.1w.tar.gz \
-D PHOTON_GFLAGS_SOURCE=https://github.com/gflags/gflags/archive/refs/tags/v2.2.2.tar.gz \
-D PHOTON_GOOGLETEST_SOURCE=https://github.com/google/googletest/archive/refs/tags/release-1.12.1.tar.gz \
-D PHOTON_BUILD_OCF_CACHE=ON  
```

--------------------------------

### Initialize Photon Environment

Source: https://photonlibos.github.io/docs/introduction/write-first-example

Initializes the Photon environment and ensures resources are cleaned up using the DEFER macro.

```cpp
#include <photon/photon.h>  
#include <photon/thread/std-compat.h>  
  
int main() {  
    int ret = photon::init(photon::INIT_EVENT_DEFAULT, photon::INIT_IO_NONE);  
    if (ret != 0) {  
        return -1;  
    }  
    DEFER(photon::fini());  
    // ...  
}  
```

--------------------------------

### Configure CMakeLists.txt for Photon Integration

Source: https://photonlibos.github.io/docs/introduction/how-to-integrate

Use FetchContent to include the Photon repository or add it as a subdirectory. Ensure internal options are set before making the library available.

```cmake
cmake_minimum_required(VERSION 3.14 FATAL_ERROR)  
  
# Suppose this is your existing project  
project(my_project)  
  
# Set some options internally used in Photon  
set(PHOTON_ENABLE_URING OFF CACHE INTERNAL "Enable iouring")  
set(PHOTON_CXX_STANDARD 14 CACHE INTERNAL "C++ standard")  
  
# 1. Fetch Photon repo with specific tag or branch  
include(FetchContent)  
FetchContent_Declare(  
    photon  
    GIT_REPOSITORY https://github.com/alibaba/PhotonLibOS.git  
    GIT_TAG main  
)  
FetchContent_MakeAvailable(photon)  
  
# 2. Submodule  
add_subdirectory(photon)  
```

--------------------------------

### Create Photon Threads

Source: https://photonlibos.github.io/docs/introduction/write-first-example

Demonstrates creating threads using global functions, lambdas, and class member functions via the photon_std namespace.

```cpp
// Global function  
int func(int a, char* b) {}  
  
// Use global function to create a thread.  
// Will be automatically joined when thread object destructed, unless been detached.  
photon_std::thread th(func, 1, '2');  
th.detach();  
  
// Create a thread with anonymous function (lambda)  
photon_std::thread th([&] {  
    // Access variables directly in the context  
});  
  
// Create a thread with class member function  
class A {  
    void f() {  
        new photon_std::thread(&A::g, this, 1, '2');  
    }  
    void g(int a, char* b) {}  
};  
```

--------------------------------

### Clone the source repository

Source: https://photonlibos.github.io/docs/introduction/how-to-build

Use git to download the PhotonLibOS source code.

```bash
git clone https://github.com/alibaba/PhotonLibOS.git  
```

--------------------------------

### Get thread vCPU

Source: https://photonlibos.github.io/docs/api/thread

Retrieves the vCPU associated with a specific thread, defaulting to the current thread.

```cpp
vcpu_base* get_vcpu(thread* th = CURRENT);  
```

--------------------------------

### Create and write to a local filesystem

Source: https://photonlibos.github.io/docs/api/filesystem-and-io

Uses the localfs adaptor to perform file operations. Requires the inclusion of <photon/fs/localfs.h>.

```cpp
auto fs = photon::fs::new_localfs_adaptor(".", photon::fs::ioengine_psync);  
if (!fs) {  
    LOG_ERRNO_RETURN(0, -1, "failed to create fs");  
}  
DEFER(delete fs);  
  
auto file = fs->open("test-file", O_WRONLY | O_CREAT | O_TRUNC, 0644);  
if (!file) {  
    LOG_ERRNO_RETURN(0, -1, "failed to open file");  
}  
DEFER(delete file);  
  
ssize_t n_written = file->write(buf, 4096);
```

--------------------------------

### Run fio benchmark command

Source: https://photonlibos.github.io/docs/performance/file-io-performance

Executes a standard fio random read benchmark for comparison against Photon.

```bash
fio --filename=/dev/nvme0n1p1 --direct=1 --ioengine=libaio --iodepth=128 --rw=randread --bs=4k --size=100% --group_reporting --name=randread --numjobs=1
```

--------------------------------

### Create and Manage Thread Pools

Source: https://photonlibos.github.io/docs/api/thread

Demonstrates initializing thread pools on the heap or stack and creating threads within them.

```cpp
// on heap  
auto p1 = photon::ThreadPoolBase::new_thread_pool(100);  
auto th1 = p1->thread_create(&func, nullptr);  
  
// on stack  
photon::ThreadPool<400> p2;  
auto th2 = p2.thread_create(&func, nullptr);
```

--------------------------------

### Initialize General TCP Sockets

Source: https://photonlibos.github.io/docs/api/network

Standard TCP client and server socket creation.

```cpp
ISocketClient* new_tcp_socket_client();  
ISocketServer* new_tcp_socket_server();  
```

--------------------------------

### Manually Initialize vCPU Environment

Source: https://photonlibos.github.io/docs/api/vcpu-and-multicore

Initializes the Photon environment within a manually created OS thread and migrates a thread to a specific vCPU.

```cpp
std::thread([]{  
    photon::init();  
    DEFER(photon::fini());  
      
    auto th = photon::thread_create11(func);  
    photon::thread_migrate(th, vcpu);  
}).detach();  
```

--------------------------------

### Create a TCP Socket Server

Source: https://photonlibos.github.io/docs/introduction/write-first-example

Sets up a TCP server with a handler to process incoming socket streams and listens on a specific port.

```cpp
#include <photon/net/socket.h>  
  
auto server = photon::net::new_tcp_socket_server();  
if (server == nullptr) {  
    LOG_ERRNO_RETURN(0, -1, "failed to create tcp server");  
}  
DEFER(delete server);  
  
auto handler = [&](photon::net::ISocketStream* stream) -> int {         
    char buf[1024];  
    ssize_t ret = stream->recv(buf, 1024);  
    if (ret <= 0) {  
        LOG_ERRNO_RETURN(0, -1, "failed to read socket");  
    }       
    return 0;  
};  
  
server->set_handler(handler);  
server->bind_v4localhost(9527);  
server->listen();  
  
LOG_INFO("Server is listening for port ` ...", 9527);  
server->start_loop(true);  

```

--------------------------------

### Initialize Photon Environment

Source: https://photonlibos.github.io/docs/api/env

Initializes the coroutine stack on the current vCPU. Blocking function calls should be avoided after this initialization.

```cpp
int photon::init(uint64_t event_engine = INIT_EVENT_DEFAULT, uint64_t io_engine = INIT_IO_DEFAULT);  
```

--------------------------------

### photon::init

Source: https://photonlibos.github.io/docs/api/env

Initializes the coroutine stack on the current vCPU and configures the event and IO engines.

```APIDOC
## int photon::init(uint64_t event_engine, uint64_t io_engine)

### Description
Initializes the coroutine stack on the current vCPU. After initialization, you can create Photon threads and migrate them to other vCPUs. Blocking function calls should not be invoked after this initialization.

### Parameters
- **event_engine** (uint64_t) - Optional - The event engine to use. Supported: INIT_EVENT_NONE, INIT_EVENT_DEFAULT, INIT_EVENT_EPOLL, INIT_EVENT_IOURING, INIT_EVENT_KQUEUE.
- **io_engine** (uint64_t) - Optional - The IO engine to use. Supported: INIT_IO_NONE, INIT_IO_LIBAIO, INIT_IO_LIBCURL, INIT_IO_SOCKET_EDGE_TRIGGER, INIT_IO_EXPORTFS, INIT_IO_FSTACK_DPDK.

### Return
Returns 0 on success, returns -1 on error.
```

--------------------------------

### Run Photon IO performance test

Source: https://photonlibos.github.io/docs/performance/file-io-performance

Executes the Photon IO performance test program on a specified disk device using io_uring.

```bash
./io-perf --disk_path=/dev/nvme0n1 --disk_size=3000000000000 --io_depth=128 --io_size=4096 --io_uring
```

--------------------------------

### Perform File IO Operations

Source: https://photonlibos.github.io/docs/introduction/write-first-example

Initializes a local filesystem adaptor and performs write operations on a file.

```cpp
#include <photon/fs/localfs.h>  
  
auto fs = photon::fs::new_localfs_adaptor(".", photon::fs::ioengine_psync);  
if (!fs) {  
    LOG_ERRNO_RETURN(0, -1, "failed to create fs");  
}  
DEFER(delete fs);  
  
auto file = fs->open("test-file", O_WRONLY | O_CREAT | O_TRUNC, 0644);  
if (!file) {  
    LOG_ERRNO_RETURN(0, -1, "failed to open file");  
}  
DEFER(delete file);  
  
ssize_t n_written = file->write(buf, 4096);  
```

--------------------------------

### Initialize io_uring Sockets

Source: https://photonlibos.github.io/docs/api/network

High-performance sockets using native io_uring IO, recommended for high-connection, low-traffic scenarios.

```cpp
ISocketClient* new_iouring_tcp_client();  
ISocketServer* new_iouring_tcp_server();  
```

--------------------------------

### photon::fs::new_localfs_adaptor

Source: https://photonlibos.github.io/docs/api/filesystem-and-io

Creates a new local filesystem adaptor instance.

```APIDOC
## photon::fs::new_localfs_adaptor

### Description
Creates a new local filesystem adaptor for the specified path using the provided IO engine.

### Signature
`auto fs = photon::fs::new_localfs_adaptor(const char* path, ioengine_t engine);`

### Parameters
- **path** (const char*) - The root path for the filesystem.
- **engine** (ioengine_t) - The IO engine to use (e.g., photon::fs::ioengine_psync).
```

--------------------------------

### Build and Run Network Performance Tests

Source: https://photonlibos.github.io/docs/performance/network-performance

Commands to compile the performance test suite and execute the server and client components.

```bash
cmake -B build -D PHOTON_BUILD_TESTING=1 -D PHOTON_ENABLE_URING=1 -D CMAKE_BUILD_TYPE=Release  
cmake --build build -j 8 -t net-perf  
```

```bash
./build/output/net-perf -port 9527 -buf_size 512  
```

```bash
./build/output/net-perf -client -client_mode streaming -ip <server_ip> -port 9527 -buf_size 512  
```

```bash
./build/output/net-perf -client -client_mode ping-pong -ip <server_ip> -port 9527 -buf_size 512 -client_connection_num 100  
```

--------------------------------

### Create a TCP Socket Client

Source: https://photonlibos.github.io/docs/introduction/write-first-example

Initializes a TCP client, connects to a specified endpoint, and sends data through the stream.

```cpp
#include <photon/net/socket.h>  
  
auto client = photon::net::new_tcp_socket_client();  
if (client == nullptr) {  
    LOG_ERRNO_RETURN(0, -1, "failed to create tcp client");  
}  
DEFER(delete client);  
  
photon::net::EndPoint ep("127.0.0.1:9527");  
auto stream = client->connect(ep);  
if (!stream) {  
    LOG_ERRNO_RETURN(0, -1, "failed to connect server");  
}  
DEFER(delete stream);  
  
// Send data to socket  
char buf[1024];  
if (stream->send(buf, 1024) != 1024) {  
    LOG_ERRNO_RETURN(0, -1, "failed to write socket");  
}  

```

--------------------------------

### Build the project from source

Source: https://photonlibos.github.io/docs/introduction/how-to-build

Compile the library using CMake. Note that macOS requires specifying the OpenSSL root directory.

```bash
cd PhotonLibOS  
cmake -B build  
cmake --build build -j 8  
```

```bash
cd PhotonLibOS  
cmake -B build  
cmake --build build -j 8  
```

```bash
cd PhotonLibOS  
cmake -B build -D OPENSSL_ROOT_DIR=/usr/local/opt/openssl@1.1  
cmake --build build -j 8  
```

--------------------------------

### Link Photon Statically to an Application

Source: https://photonlibos.github.io/docs/introduction/how-to-integrate

Link the photon_static target to your executable to include Photon statically.

```cmake
add_executable(my_app ${SOURCES})  
target_link_libraries(my_app photon_static)  
```

--------------------------------

### Include Photon HTTP Headers

Source: https://photonlibos.github.io/docs/api/network

Header inclusion for the native, dependency-free Photon HTTP framework.

```cpp
#include <photon/net/http/client.h>  
#include <photon/net/http/server.h>  
```

--------------------------------

### Create a new thread with thread_create

Source: https://photonlibos.github.io/docs/api/thread

Initializes a new thread and adds it to the RunQueue. Ensure passed parameters have a lifecycle that outlasts the thread execution.

```cpp
photon::thread* photon::thread_create(thread_entry start, void* arg,  
                                      uint64_t stack_size = DEFAULT_STACK_SIZE,  
                                      uint16_t reserved_space = 0);  
```

--------------------------------

### Load Photon GDB Extension

Source: https://photonlibos.github.io/docs/miscellaneous/debugging

Load the extension into the GDB environment to enable Photon-specific debugging commands.

```gdb
(gdb) source <repo_dir>/tools/photongdb.py   
INFO Photon-GDB-extension loaded  
```

--------------------------------

### Inspect Photon Thread Stack with photon_fr

Source: https://photonlibos.github.io/docs/miscellaneous/debugging

Switches the GDB context to a specific Photon thread frame to enable backtrace inspection. Requires prior execution of photon_init.

```gdb
(gdb) photon_fr 1  
SWITCH to 0x7ffff2bf9ac8 0x7ffff2bf9ae0 0x7ffff5014ceb  
(gdb) bt  
#0  photon::switch_context (from=0x7ffff2bf9bc0, to=0x736c50) at photon/thread.cpp:478  
#1  0x00007ffff5014d22 in photon::switch_context (from=0x7ffff2bf9bc0, new_state=photon::READY, to=0x736c50) at photon/thread.cpp:482  
#2  0x00007ffff5010b51 in photon::thread_yield_to (th=0x736c50) at photon/thread.cpp:575  
#3  0x00007ffff5010465 in photon::thread_stub () at photon/thread.cpp:386  
#4  0x0000000000000000 in ?? ()  
(gdb) photon_fr 0  
SWITCH to 0x7fffffffd000 0x7fffffffd000 0x4282e0  
(gdb) bt  
#0  0x00000000004282e0 in <lambda(ILogOutput*)>::operator()(ILogOutput *) const (__closure=0x7fffffffd044, __output___LINE__=0x706280 <_log_output_null>)  
    at test/test.cpp:132  
#1  0x00000000004488ba in LogBuilder<log_format()::<lambda(ILogOutput*)> >::~LogBuilder(void) (this=0x7fffffffd040, __in_chrg=<optimized out>)  
    at test/../alog.h:519  
#2  0x0000000000428398 in log_format () at test/test.cpp:133  
#3  0x00000000004283c9 in ALog_fmt_perf_1m_Test::TestBody (this=0x736c00) at test/test.cpp:140  
#4  0x00000000004b6d13 in void testing::internal::HandleExceptionsInMethodIfSupported<testing::Test, void>(testing::Test*, void (testing::Test::*)(), char const*) ()  
#5  0x00000000004abeaa in testing::Test::Run() ()  
#6  0x00000000004abff8 in testing::TestInfo::Run() ()  
#7  0x00000000004ac0d5 in testing::TestCase::Run() ()  
#8  0x00000000004ac3c0 in testing::internal::UnitTestImpl::RunAllTests() ()  
#9  0x00000000004b7223 in bool testing::internal::HandleExceptionsInMethodIfSupported<testing::internal::UnitTestImpl, bool>(testing::internal::UnitTestImpl*, bool (testing::internal::UnitTestImpl::*)(), char const*) ()  
#10 0x00000000004ac6a3 in testing::UnitTest::Run() ()  
#11 0x0000000000457f24 in RUN_ALL_TESTS () at ../../.dep_create_cache/var/alicpp/apsara/alicpp/built/gcc-4.9.2/gtest-1.7.0/include/gtest/gtest.h:2288  
#12 0x0000000000447737 in main (argc=1, argv=0x7fffffffd4d8) at test/test.cpp:1761
```

--------------------------------

### Raw AIO wrapper functions

Source: https://photonlibos.github.io/docs/api/filesystem-and-io

Provides interfaces for libaio and posixaio. Note that file descriptors must be opened with O_DIRECT and buffers must be aligned for libaio operations.

```cpp
// `fd` must be opened with O_DIRECT, and the buffers must be aligned  
ssize_t libaio_pread(int fd, void *buf, size_t count, off_t offset);  
ssize_t libaio_preadv(int fd, const struct iovec *iov, int iovcnt, off_t offset);  
ssize_t libaio_pwrite(int fd, const void *buf, size_t count, off_t offset);  
ssize_t libaio_pwritev(int fd, const struct iovec *iov, int iovcnt, off_t offset);  
static int libaio_fsync(int fd) { return 0; }  
  
ssize_t posixaio_pread(int fd, void *buf, size_t count, off_t offset);  
ssize_t posixaio_pwrite(int fd, const void *buf, size_t count, off_t offset);  
int posixaio_fsync(int fd);  
int posixaio_fdatasync(int fd);
```

--------------------------------

### Configure dynamic linking for specific libraries

Source: https://photonlibos.github.io/docs/introduction/how-to-build

Build dependencies from source while dynamically linking to system-provided libcurl and libssl.

```bash
cmake -B build -D CMAKE_BUILD_TYPE=RelWithDebInfo \
-D PHOTON_BUILD_DEPENDENCIES=ON \
-D PHOTON_AIO_SOURCE=https://pagure.io/libaio/archive/libaio-0.3.113/libaio-0.3.113.tar.gz \
-D PHOTON_CURL_SOURCE="" \
-D PHOTON_OPENSSL_SOURCE=""  
```

--------------------------------

### List Photon Threads on vCPU

Source: https://photonlibos.github.io/docs/miscellaneous/debugging

Lists all Photon threads currently on the vCPU. Requires photon_init to have been called.

```gdb
(gdb) photon_ls  
CURRENT [0] 0x5555558a9e20 0x7fffffffdb30 0x7fffffffe1a0 0x55555556a029  
READY [1] 0x7ffff6afb340 0x7ffff6afb1b0 0x7ffff6afb1d0 0x5555555696e0  
SLEEP [2] 0x5555558c0740 0x5555558c0310 0x5555558c0310 0x5555558c0740  
SLEEP [3] 0x7ffff6165b40 0x7ffff6165690 0x7ffff6165690 0x7ffff6165b40  
```

--------------------------------

### Initialize Photon Thread Lookup Mode

Source: https://photonlibos.github.io/docs/miscellaneous/debugging

Initializes the lookup mode and stores stack registers. Do not continue or step-in while in this mode.

```gdb
(gdb) photon_init  
WARNING Entered photon thread lookup mode. PLEASE do not trying step-in or continue before `photon_fini`  
  
(gdb) p $saved_rsp  
$1 = 140737488343040  
(gdb) p $saved_rbp  
$2 = 140737488343040  
(gdb) p $saved_rip  
$3 = 4358880  
  
(gdb) photon_ls  
CURRENT [0] 0x5555558a9e20 0x7fffffffdb30 0x7fffffffe1a0 0x55555556a029  
READY [1] 0x7ffff6afb340 0x7ffff6afb1b0 0x7ffff6afb1d0 0x5555555696e0  
SLEEP [2] 0x5555558c0740 0x5555558c0310 0x5555558c0310 0x5555558c0740  
SLEEP [3] 0x7ffff6165b40 0x7ffff6165690 0x7ffff6165690 0x7ffff6165b40  
```

--------------------------------

### Link Photon Dynamically to an Application

Source: https://photonlibos.github.io/docs/introduction/how-to-integrate

Link the photon_shared target to your executable to include Photon dynamically.

```cmake
add_executable(my_app ${SOURCES})  
target_link_libraries(my_app photon_shared)  
```

--------------------------------

### Initialize SMC Sockets

Source: https://photonlibos.github.io/docs/api/network

RDMA-based socket implementation using the SMC-R protocol.

```cpp
ISocketClient* new_smc_socket_client();  
ISocketServer* new_smc_socket_server();  
```

--------------------------------

### Initialize UDS Sockets

Source: https://photonlibos.github.io/docs/api/network

Unix Domain Socket creation with an optional autoremove parameter for server cleanup.

```cpp
ISocketClient* new_uds_client();  
ISocketServer* new_uds_server(bool autoremove = false);  
```

--------------------------------

### Migrate a thread

Source: https://photonlibos.github.io/docs/api/thread

Moves a READY state thread to a different vCPU. Recommended only when encountering CPU bottlenecks.

```cpp
int photon::thread_migrate(photon::thread* th, photon::vcpu_base* vcpu);  
```

--------------------------------

### WorkPool Constructor

Source: https://photonlibos.github.io/docs/api/vcpu-and-multicore

Initializes a new WorkPool to manage multiple vCPUs for multi-core utilization.

```APIDOC
### Constructor
WorkPool(size_t vcpu_num, int ev_engine = 0, int io_engine = 0, int thread_mod = -1);

### Parameters
- **vcpu_num** (size_t) - Required - Number of vCPUs to be created.
- **ev_engine** (int) - Optional - Event engine initialization type.
- **io_engine** (int) - Optional - IO engine initialization type.
- **thread_mod** (int) - Optional - Thread working mode (-1: non-thread, 0: create thread per task, >0: thread pool size).
```

--------------------------------

### AIO Wrapper Functions

Source: https://photonlibos.github.io/docs/api/filesystem-and-io

Raw API wrappers for libaio and posixaio operations.

```APIDOC
## AIO Wrapper Functions

### Description
Provides asynchronous IO operations for libaio and posixaio. Note that file descriptors must be opened with O_DIRECT and buffers must be aligned.

### Functions
- `ssize_t libaio_pread(int fd, void *buf, size_t count, off_t offset);`
- `ssize_t libaio_pwrite(int fd, const void *buf, size_t count, off_t offset);`
- `ssize_t posixaio_pread(int fd, void *buf, size_t count, off_t offset);`
- `ssize_t posixaio_pwrite(int fd, const void *buf, size_t count, off_t offset);`
```

--------------------------------

### List Available Photon GDB Commands

Source: https://photonlibos.github.io/docs/miscellaneous/debugging

The extension adds several commands to the GDB environment for thread management and inspection.

```gdb
photon_current  
photon_ls  
photon_init  
photon_fini  
photon_rst  
photon_fr  
```

--------------------------------

### Initialize Zerocopy TCP Sockets

Source: https://photonlibos.github.io/docs/api/network

TCP sockets utilizing kernel zerocopy, requiring kernel 4.15+ to reduce CPU overhead for large buffers.

```cpp
ISocketClient* new_zerocopy_tcp_client();  
ISocketServer* new_zerocopy_tcp_server();  
```

--------------------------------

### photon::thread_migrate

Source: https://photonlibos.github.io/docs/api/thread

Migrates a READY state thread to another vCPU.

```APIDOC
## int photon::thread_migrate(photon::thread* th, photon::vcpu_base* vcpu)

### Description
Migrate a READY state thread to another vCPU.

### Parameters
- **th** (photon::thread*) - Required - Target thread.
- **vcpu** (photon::vcpu_base*) - Required - Target vCPU.
```

--------------------------------

### WorkPool Constructor

Source: https://photonlibos.github.io/docs/api/vcpu-and-multicore

Initializes a WorkPool to manage multiple vCPUs for multi-core execution.

```cpp
WorkPool(size_t vcpu_num, int ev_engine = 0, int io_engine = 0, int thread_mod = -1);  
```

--------------------------------

### Raw io_uring wrapper functions

Source: https://photonlibos.github.io/docs/api/filesystem-and-io

Provides asynchronous IO operations using io_uring. Requires inclusion of <photon/io/iouring-wrapper.h>.

```cpp
ssize_t iouring_pread(int fd, void* buf, size_t count, off_t offset, uint64_t timeout);  
ssize_t iouring_pwrite(int fd, const void* buf, size_t count, off_t offset, uint64_t timeout);  
ssize_t iouring_preadv(int fd, const iovec* iov, int iovcnt, off_t offset, uint64_t timeout);  
ssize_t iouring_pwritev(int fd, const iovec* iov, int iovcnt, off_t offset, uint64_t timeout);  
ssize_t iouring_send(int fd, const void* buf, size_t len, int flags, uint64_t timeout);  
ssize_t iouring_recv(int fd, void* buf, size_t len, int flags, uint64_t timeout);  
ssize_t iouring_sendmsg(int fd, const msghdr* msg, int flags, uint64_t timeout);  
ssize_t iouring_recvmsg(int fd, msghdr* msg, int flags, uint64_t timeout);  
int iouring_connect(int fd, const sockaddr* addr, socklen_t addrlen, uint64_t timeout);  
int iouring_accept(int fd, sockaddr* addr, socklen_t* addrlen, uint64_t timeout);  
int iouring_fsync(int fd);  
int iouring_fdatasync(int fd);  
int iouring_open(const char* path, int flags, mode_t mode);  
int iouring_mkdir(const char* path, mode_t mode);  
int iouring_close(int fd);
```

--------------------------------

### photon_std API Overview

Source: https://photonlibos.github.io/docs/api/std-compatible-api

Overview of the classes and functions available in the photon_std namespace for C++ standard library compatibility.

```APIDOC
## photon_std API

### Namespace
`photon_std::`

### Headers
`<photon/thread/std-compat.h>`

### Supported Classes
- `thread`
- `mutex`
- `condition_variable`
- `recursive_mutex`
- `timed_mutex`
- `lock_guard`
- `unique_lock`

### Supported Functions
- `this_thread::yield()`
- `this_thread::get_id()`
- `this_thread::sleep_for()`
- `this_thread::sleep_until()`

### Extended Functions
- `work_pool_init`: Create a global WorkPool
- `work_pool_fini`: Destroy the WorkPool
- `this_thread::migrate()`: Migrate current thread to another vCPU in the WorkPool
```

--------------------------------

### Include libcurl Headers

Source: https://photonlibos.github.io/docs/api/network

Header inclusion for using the libcurl-based asynchronous HTTP client.

```cpp
#include <photon/net/curl.h>  
```

--------------------------------

### Socket Creation Functions

Source: https://photonlibos.github.io/docs/api/network

Functions to instantiate various types of socket clients and servers.

```APIDOC
## Socket Creation

### Description
Functions to create different types of socket clients and servers including TCP, UDS, io_uring, zerocopy, Edge-Triggered, SMC, and F-Stack/DPDK.

### Methods
- `ISocketClient* new_tcp_socket_client()`
- `ISocketServer* new_tcp_socket_server()`
- `ISocketClient* new_uds_client()`
- `ISocketServer* new_uds_server(bool autoremove = false)`
- `ISocketClient* new_iouring_tcp_client()`
- `ISocketServer* new_iouring_tcp_server()`
- `ISocketClient* new_zerocopy_tcp_client()`
- `ISocketServer* new_zerocopy_tcp_server()`
- `ISocketClient* new_et_tcp_socket_client()`
- `ISocketServer* new_et_tcp_socket_server()`
- `ISocketClient* new_smc_socket_client()`
- `ISocketServer* new_smc_socket_server()`
- `ISocketClient* new_fstack_dpdk_socket_client()`
- `ISocketServer* new_fstack_dpdk_socket_server()`
```

--------------------------------

### Initialize Edge-Triggered TCP Sockets

Source: https://photonlibos.github.io/docs/api/network

TCP socket implementation using edge-triggered event notification.

```cpp
ISocketClient* new_et_tcp_socket_client();  
ISocketServer* new_et_tcp_socket_server();  
```

--------------------------------

### C++11 thread_create11 wrappers

Source: https://photonlibos.github.io/docs/api/thread

Provides C++11 syntax wrappers for thread creation, supporting global functions, functors, and member functions.

```cpp
template<typename F, typename... ARGUMENTS>  
photon::thread* photon::thread_create11(F f, ARGUMENTS&& ...args);              // (1)  
  
template<typename FUNCTOR, typename... ARGUMENTS>  
photon::thread* photon::thread_create11(FUNCTOR&& f, ARGUMENTS&& ...args);      // (2)  
  
template<typename CLASS, typename F, typename... ARGUMENTS>  
photon::thread* photon::thread_create11(F f, CLASS* obj, ARGUMENTS&& ...args);  // (3)  
```

--------------------------------

### Inspect Current Photon Thread

Source: https://photonlibos.github.io/docs/miscellaneous/debugging

Prints the structure of the currently running Photon thread. This command has no side effects.

```gdb
(gdb) photon_current  
CURRENT {<intrusive_list_node<photon::thread>> = {<__intrusive_list_node> = {__prev_ptr = 0x7ffff2bf9bc0, __next_ptr = 0x7ffff2bf9bc0}, <No data fields>}, state = photon::RUNNING, error_number = 0, idx = -172836528, flags = 0, reserved = 7564776, joinable = false, shutting_down = false, lock = {_lock = {<std::__atomic_flag_base> = {_M_i = false}, <No data fields>}}, waitq = 0x0, vcpu = 0x7ffff7db5600 <photon::vcpus>, start = 0x736de8, arg = 0x0, retval = 0x736fe8, buf = 0x7ffff7dd46c0 <(anonymous namespace)::c_locale_impl> "\020", stack = {_ptr = 0x7fffffffd0c8}, ts_wakeup = 0, cond = {<photon::waitq> = {q = {th = 0x0, lock = {_lock = {<std::__atomic_flag_base> = {_M_i = false}, <No data fields>}}}}, <No data fields>}}  
```

--------------------------------

### Initialize F-Stack DPDK Sockets

Source: https://photonlibos.github.io/docs/api/network

Coroutine-based network sockets running in DPDK polling mode via F-Stack.

```cpp
ISocketClient* new_fstack_dpdk_socket_client();  
ISocketServer* new_fstack_dpdk_socket_server();  
```

--------------------------------

### photon::thread_create11

Source: https://photonlibos.github.io/docs/api/thread

C++11 syntax wrapper for thread_create that supports multiple arguments and functors.

```APIDOC
## photon::thread_create11

### Description
C++11 syntax wrapper for thread_create. Multiple arguments are allowed and forwarded to the new thread by value.

### Signatures
1. `template<typename F, typename... ARGUMENTS> photon::thread* photon::thread_create11(F f, ARGUMENTS&& ...args);`
2. `template<typename FUNCTOR, typename... ARGUMENTS> photon::thread* photon::thread_create11(FUNCTOR&& f, ARGUMENTS&& ...args);`
3. `template<typename CLASS, typename F, typename... ARGUMENTS> photon::thread* photon::thread_create11(F f, CLASS* obj, ARGUMENTS&& ...args);`

### Return
- **photon::thread*** - Pointer to the new thread.
```

--------------------------------

### photon::spinlock

Source: https://photonlibos.github.io/docs/api/lock-and-synchronization

A spinlock implementation for synchronization.

```APIDOC
## class photon::spinlock

### Methods
- **lock()**: Acquires the spinlock.
- **try_lock()**: Attempts to acquire the spinlock.
- **unlock()**: Releases the spinlock.
```

--------------------------------

### photon::thread_enable_join

Source: https://photonlibos.github.io/docs/api/thread

Enables or disables the ability to join a thread.

```APIDOC
## photon::thread_enable_join

### Description
Enables or disables joining for a specific thread. Once join is enabled, the thread will remain existing until being joined to prevent resource leaks.

### Signature
`photon::join_handle* photon::thread_enable_join(photon::thread* th, bool flag = true);`

### Parameters
- **th** (photon::thread*) - Required - Thread pointer.
- **flag** (bool) - Optional - Enable or disable (default true).

### Return
- **photon::join_handle*** - Pointer of a join_handle.
```

--------------------------------

### Join a thread

Source: https://photonlibos.github.io/docs/api/thread

Joins a thread using a join handle. Do not join exited or non-existent threads to avoid core dumps.

```cpp
void photon::thread_join(photon::join_handle* jh);  
```

--------------------------------

### photon::thread_join

Source: https://photonlibos.github.io/docs/api/thread

Joins a thread. Note that joining an exited or non-existent thread will cause a core dump.

```APIDOC
## void photon::thread_join(photon::join_handle* jh)

### Description
Join a thread. You cannot join an exited or non-existent thread.

### Parameters
- **jh** (photon::join_handle*) - Required - Pointer of a join_handle obtained from thread_enable_join.
```

--------------------------------

### Add Photon to a Static Library

Source: https://photonlibos.github.io/docs/introduction/how-to-integrate

Link photon_static as a private dependency when building a static library.

```cmake
add_library(my_lib STATIC ${SOURCES})  
target_link_libraries(my_lib PRIVATE photon_static)  
```

--------------------------------

### WorkPool::thread_migrate

Source: https://photonlibos.github.io/docs/api/vcpu-and-multicore

Migrates a specific Photon thread to a target vCPU within the WorkPool.

```APIDOC
### Method
int thread_migrate(photon::thread* th = CURRENT, size_t index = -1UL);

### Parameters
- **th** (photon::thread*) - Optional - The thread to migrate.
- **index** (size_t) - Optional - The index of the target vCPU. Defaults to round-robin if out of range.
```

--------------------------------

### ISocketClient

Source: https://photonlibos.github.io/docs/api/network

Interface for initiating network connections to remote endpoints or Unix Domain Sockets.

```APIDOC
## ISocketClient::connect

### Description
Connects to a remote endpoint or a Unix Domain Socket path.

### Methods
- `ISocketStream* connect(const EndPoint& remote, const EndPoint* local = nullptr)`: Connects to a remote endpoint, optionally binding to a local address.
- `ISocketStream* connect(const char* path, size_t count = 0)`: Connects to a Unix Domain Socket.
```

--------------------------------

### io_uring Wrapper Functions

Source: https://photonlibos.github.io/docs/api/filesystem-and-io

Raw API wrappers for io_uring operations.

```APIDOC
## io_uring Wrapper Functions

### Description
Provides io_uring based asynchronous IO and network operations with timeout support.

### Functions
- `ssize_t iouring_pread(int fd, void* buf, size_t count, off_t offset, uint64_t timeout);`
- `ssize_t iouring_pwrite(int fd, const void* buf, size_t count, off_t offset, uint64_t timeout);`
- `ssize_t iouring_send(int fd, const void* buf, size_t len, int flags, uint64_t timeout);`
- `ssize_t iouring_recv(int fd, void* buf, size_t len, int flags, uint64_t timeout);`
- `int iouring_open(const char* path, int flags, mode_t mode);`
- `int iouring_close(int fd);`
```

--------------------------------

### photon::thread_create

Source: https://photonlibos.github.io/docs/api/thread

Creates a new thread and adds it to the RunQueue for the scheduler to execute.

```APIDOC
## photon::thread_create

### Description
Creates a new thread, put it into the RunQueue. Leave it to the scheduler to decide when to run. No thread yield in this call, which means the caller will continue its execution.

### Signature
`photon::thread* photon::thread_create(thread_entry start, void* arg, uint64_t stack_size = DEFAULT_STACK_SIZE, uint16_t reserved_space = 0);`

### Parameters
- **start** (thread_entry) - Required - Thread function's entry point (void* (*)(void*)).
- **arg** (void*) - Required - Thread function's sole argument.
- **stack_size** (uint64_t) - Optional - Size of the coroutine stack (default 8MB).
- **reserved_space** (uint16_t) - Optional - Space for large arguments (default 0).

### Return
- **photon::thread*** - Pointer to the new thread.
```

--------------------------------

### Add Photon to a Shared Library

Source: https://photonlibos.github.io/docs/introduction/how-to-integrate

Use whole-archive flags when linking libphoton.a into a shared library to ensure symbols are included.

```cmake
add_library(my_lib SHARED ${SOURCES})  
target_link_libraries(my_lib PRIVATE -Wl,--whole-archive libphoton.a -Wl,--no-whole-archive)  
```

--------------------------------

### Manage Thread Concurrency

Source: https://photonlibos.github.io/docs/introduction/write-first-example

Spawns multiple threads and waits for their completion using the join method.

```cpp
std::vector<photon_std::thread> threads;  
for (int i = 0; i < 100; ++i) {  
    threads.emplace_back(func, 1, '2');  
}  
for (auto& th : threads) {  
    th.join();  
}  
```

--------------------------------

### WorkPool::async_call

Source: https://photonlibos.github.io/docs/api/vcpu-and-multicore

Submits a task to the WorkPool for asynchronous execution across vCPUs.

```APIDOC
### Method
int WorkPool::async_call(Task* task);

### Description
Uses an MPMC Queue to deliver messages to multiple vCPUs for execution without waiting for completion.

### Parameters
- **task** (Task*) - Required - A pointer to a task (usually a new-ed lambda) to be executed.
```

--------------------------------

### Bind Class Member Function to Delegate

Source: https://photonlibos.github.io/docs/api/delegate_callback

Passing a class instance and member function pointer to the delegate.

```cpp
class MyClass {  
    // ...  
public:  
    File* OpenFile_MF(const string& fileName, const char* mode) { ... }  
    //...  
};  
  
MyClass myClass;  
  
ProcessFiles(fileNames, { &myClass, &MyClass::OpenFile_MF });
```

--------------------------------

### Finalize Photon Environment

Source: https://photonlibos.github.io/docs/api/env

Destroys ancillary IO threads, stops the event engine, and deallocates the coroutine stack.

```cpp
int photon::fini();  
```

--------------------------------

### Synchronize Threads with Condition Variables

Source: https://photonlibos.github.io/docs/introduction/write-first-example

Uses a mutex and condition variable to coordinate between consumer and producer threads.

```cpp
bool condition = false;  
photon_std::mutex mu;  
photon_std::condition_variable cv;  
  
// Consumer thread  
photon_std::thread([&]{  
    auto timeout = std::chrono::duration<std::chrono::seconds>(10);  
    photon_std::unique_lock<photon_std::mutex> lock(mu);  
    while (!condition) {  
        cv.wait(lock, timeout);  
    }  
}).detach();  
  
// Producer thread  
photon_std::thread([&]{  
    photon_std::lock_guard<photon_std::mutex> lock(mu);  
    condition = true;  
    cv.notify_one();  
}).detach();  
```

--------------------------------

### photon::semaphore

Source: https://photonlibos.github.io/docs/api/lock-and-synchronization

A counting semaphore for resource management.

```APIDOC
## class photon::semaphore

### Methods
- **semaphore(uint64_t count = 0)**: Constructor.
- **wait(uint64_t count, Timeout timeout = -1UL)**: Waits for the semaphore count.
- **wait_interruptible(uint64_t count, Timeout timeout = -1UL)**: Interruptible wait.
- **signal(uint64_t count)**: Increments the semaphore count.
- **count()**: Returns the current count.
```

--------------------------------

### Timer

Source: https://photonlibos.github.io/docs/api/thread

The Timer class allows for scheduling tasks using a callback function, with support for repeating or one-time execution.

```APIDOC
## Timer

### Description
Create a timer object with a callback function. The timer is implemented as a special thread and is deleted automatically after it is finished.

### Constructor
`Timer(uint64_t default_timeout, Entry on_timer, bool repeating = true, uint64_t stack_size = 1024 * 64);`

### Methods
- `int Timer::cancel()`: Cancels the timer.
- `int Timer::reset(uint64_t new_timeout = -1)`: Resets the timer with a new timeout.
- `int Timer::stop()`: Stops the timer.
```

--------------------------------

### Exit Photon Thread Lookup Mode with photon_fini

Source: https://photonlibos.github.io/docs/miscellaneous/debugging

Restores registers and exits the Photon thread lookup mode, allowing execution to continue.

```gdb
(gdb) photon_fini  
WARNING Finished photon thread lookup mode.
```

--------------------------------

### Delegate<ResultType, ArgumentTypes...>

Source: https://photonlibos.github.io/docs/api/delegate_callback

The Delegate template defines a callback mechanism. It can be initialized with a class member function (using an object pointer and the member function pointer) or a free function (using a void* context pointer and the function pointer).

```APIDOC
## Delegate<ResultType, ArgumentTypes...>

### Description
A template structure representing a callback function. It stores the address of a target function and an initial argument (either a 'this' pointer for member functions or a 'void*' context pointer for free functions).

### Prototype
```cpp
template<typename ResultType, typename...ArgumentTypes>  
struct Delegate;
```

### Usage
- **Class Member Function**: `{ &object, &Class::Method }`
- **Free Function**: `{ context_ptr, &Function }`
- **Lambda**: Supported, but binding to temporary lambdas is forbidden to prevent life-cycle issues.
```
Tokens:
Raw