Skip to content

Commit faf8776

Browse files
atsushi421atsushi421
authored
Merge pull request #3 from sykwer/api-reference
api reference
2 parents c9ee7b6 + e441cf3 commit faf8776

25 files changed

Lines changed: 4223 additions & 199 deletions

‎.github/workflows/deploy-docs.yaml‎

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,32 @@ on:
44
push:
55
branches:
66
- main
7-
paths:
8-
- mkdocs.yaml
9-
- "**/*.md"
10-
- "**/*.svg"
11-
- "**/*.png"
12-
- "**/*.jpg"
7+
workflow_dispatch:
8+
inputs:
9+
agnocast_branch:
10+
description: "Agnocast branch to generate API reference from"
11+
required: false
12+
default: "api-reference" # TODO: change to "main" after merge
1313

1414
jobs:
1515
deploy:
1616
runs-on: ubuntu-latest
1717
steps:
1818
- uses: actions/checkout@v4
19+
1920
- uses: actions/setup-python@v4
2021
with:
21-
python-version: 3.10.12
22-
- run: pip install -r requirements.txt
23-
- run: mkdocs gh-deploy --force
22+
python-version: "3.10"
23+
24+
- name: Install dependencies
25+
run: |
26+
pip install -r requirements.txt
27+
sudo apt-get update && sudo apt-get install -y doxygen
28+
29+
- name: Generate API Reference
30+
run: |
31+
BRANCH="${{ github.event.inputs.agnocast_branch || 'api-reference' }}"
32+
./generate_api.sh "$BRANCH"
33+
34+
- name: Deploy to GitHub Pages
35+
run: mkdocs gh-deploy --force

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
site/
2+
.doxygen_xml/
3+
.agnocast_src/
4+
doxygen_output/
5+
Doxyfile.generated
6+
__pycache__/

‎Doxyfile‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Doxyfile — XML-only output for API reference generation
2+
# This is NOT used to produce HTML. A Python script reads the XML
3+
# and generates a single Markdown page.
4+
5+
PROJECT_NAME = "Agnocast"
6+
OUTPUT_DIRECTORY = .doxygen_xml
7+
GENERATE_HTML = NO
8+
GENERATE_LATEX = NO
9+
GENERATE_XML = YES
10+
XML_PROGRAMLISTING = NO
11+
12+
INPUT = ../agnocast/src/agnocastlib/include/agnocast/agnocast.hpp \
13+
../agnocast/src/agnocastlib/include/agnocast/agnocast_publisher.hpp \
14+
../agnocast/src/agnocastlib/include/agnocast/agnocast_subscription.hpp \
15+
../agnocast/src/agnocastlib/include/agnocast/agnocast_smart_pointer.hpp \
16+
../agnocast/src/agnocastlib/include/agnocast/agnocast_client.hpp \
17+
../agnocast/src/agnocastlib/include/agnocast/agnocast_service.hpp \
18+
../agnocast/src/agnocastlib/include/agnocast/agnocast_timer.hpp \
19+
../agnocast/src/agnocastlib/include/agnocast/agnocast_executor.hpp \
20+
../agnocast/src/agnocastlib/include/agnocast/agnocast_single_threaded_executor.hpp \
21+
../agnocast/src/agnocastlib/include/agnocast/agnocast_multi_threaded_executor.hpp \
22+
../agnocast/src/agnocastlib/include/agnocast/agnocast_callback_isolated_executor.hpp \
23+
../agnocast/src/agnocastlib/include/agnocast/node/agnocast_node.hpp \
24+
../agnocast/src/agnocastlib/include/agnocast/node/agnocast_only_executor.hpp \
25+
../agnocast/src/agnocastlib/include/agnocast/node/agnocast_only_single_threaded_executor.hpp \
26+
../agnocast/src/agnocastlib/include/agnocast/node/agnocast_only_multi_threaded_executor.hpp \
27+
../agnocast/src/agnocastlib/include/agnocast/node/agnocast_only_callback_isolated_executor.hpp \
28+
../agnocast/src/agnocastlib/include/agnocast/node/agnocast_context.hpp \
29+
../agnocast/src/agnocastlib/include/agnocast/message_filters/subscriber.hpp \
30+
../agnocast/src/agnocastlib/include/agnocast/message_filters/synchronizer.hpp \
31+
../agnocast/src/agnocastlib/include/agnocast/message_filters/pass_through.hpp \
32+
../agnocast/src/agnocastlib/include/agnocast/message_filters/sync_policies/exact_time.hpp \
33+
../agnocast/src/agnocastlib/include/agnocast/message_filters/sync_policies/approximate_time.hpp
34+
RECURSIVE = NO
35+
FILE_PATTERNS = *.hpp
36+
37+
EXTRACT_ALL = NO
38+
EXTRACT_PRIVATE = NO
39+
EXTRACT_STATIC = NO
40+
HIDE_UNDOC_MEMBERS = YES
41+
HIDE_UNDOC_CLASSES = YES
42+
HIDE_FRIEND_COMPOUNDS = YES
43+
HIDE_IN_BODY_DOCS = YES
44+
INTERNAL_DOCS = NO
45+
JAVADOC_AUTOBRIEF = YES
46+
TYPEDEF_HIDES_STRUCT = YES
47+
48+
ENABLE_PREPROCESSING = YES
49+
MACRO_EXPANSION = YES
50+
EXPAND_ONLY_PREDEF = YES
51+
PREDEFINED = AGNOCAST_PUBLIC= \
52+
RCLCPP_PUBLIC= \
53+
RCLCPP_SMART_PTR_DEFINITIONS(x)= \
54+
RCLCPP_SMART_PTR_DEFINITIONS_NOT_COPYABLE(x)= \
55+
RCLCPP_DISABLE_COPY(x)= \
56+
RCPPUTILS_TSA_GUARDED_BY(x)= \
57+
RCPPUTILS_TSA_REQUIRES(x)=
58+
59+
QUIET = YES
60+
WARN_IF_UNDOCUMENTED = NO

‎docs/api/.pages‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,19 @@
11
nav:
2-
- ... | index.md
2+
- Overview: index.md
3+
- Free Functions: free-functions.md
4+
- Type Aliases: type-aliases.md
5+
- Node: node.md
6+
- Publisher: publisher.md
7+
- Subscription: subscription.md
8+
- TakeSubscription: takesubscription.md
9+
- PollingSubscriber: pollingsubscriber.md
10+
- ipc_shared_ptr: ipc_shared_ptr.md
11+
- Client: client.md
12+
- Service: service.md
13+
- TimerBase: timerbase.md
14+
- GenericTimer: generictimer.md
15+
- WallTimer: walltimer.md
16+
- Executors: executors.md
17+
- Options: options.md
18+
- Message Filters: message-filters.md
19+
- Environment Variables: environment-variables.md

‎docs/api/client.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
2+
# Client
3+
4+
<!-- Auto-generated — do not edit. Regenerate with: doxygen Doxyfile && python3 generate_api_reference.py -->
5+
6+
7+
### `agnocast::Client<ServiceT>`
8+
9+
Service client for zero-copy Agnocast service communication. The service/client API is experimental and may change in future versions.
10+
11+
**Example:**
12+
13+
```cpp
14+
using SrvT = example_interfaces::srv::AddTwoInts;
15+
16+
auto client = agnocast::create_client<SrvT>(this, "add_two_ints");
17+
client->wait_for_service();
18+
19+
// Send a request with a callback
20+
auto req = client->borrow_loaned_request();
21+
req->a = 1;
22+
req->b = 2;
23+
client->async_send_request(std::move(req),
24+
[this](agnocast::Client<SrvT>::SharedFuture future) {
25+
RCLCPP_INFO(get_logger(), "Result: %ld", future.get()->sum);
26+
});
27+
28+
// Or send a request and get a future
29+
auto req2 = client->borrow_loaned_request();
30+
req2->a = 3;
31+
req2->b = 4;
32+
auto future = client->async_send_request(std::move(req2));
33+
RCLCPP_INFO(get_logger(), "Result: %ld", future.get()->sum);
34+
```
35+
36+
37+
---
38+
39+
#### `FutureAndRequestId`
40+
41+
```cpp
42+
struct FutureAndRequestId
43+
```
44+
45+
Return type of async_send_request() (no-callback overload). Contains a Future and the request ID. Access the future via the future member and the request ID via request_id.
46+
47+
48+
---
49+
50+
#### `RequestT`
51+
52+
```cpp
53+
struct RequestT
54+
```
55+
56+
Request type extending ServiceT::Request with internal metadata. Use this in borrow_loaned_request() return types.
57+
58+
| Template Parameter | Description |
59+
|-----------|-------------|
60+
| `RequestT` | Request message type (derived from `ServiceT::Request`). |
61+
62+
63+
---
64+
65+
#### `ResponseT`
66+
67+
```cpp
68+
struct ResponseT
69+
```
70+
71+
Response type extending ServiceT::Response with internal metadata. Received via Future or SharedFuture.
72+
73+
| Template Parameter | Description |
74+
|-----------|-------------|
75+
| `ResponseT` | Response message type (derived from `ServiceT::Response`). |
76+
77+
78+
---
79+
80+
#### `SharedFutureAndRequestId`
81+
82+
```cpp
83+
struct SharedFutureAndRequestId
84+
```
85+
86+
Return type of async_send_request() (callback overload). Contains a SharedFuture and the request ID. Access the shared future via the future member and the request ID via request_id.
87+
88+
89+
---
90+
91+
#### `Future`
92+
93+
```cpp
94+
Future
95+
```
96+
97+
Future that resolves to the service response. Returned by async_send_request() (no-callback overload).
98+
99+
100+
---
101+
102+
#### `SharedFuture`
103+
104+
```cpp
105+
SharedFuture
106+
```
107+
108+
Shared future that resolves to the service response. Passed to the callback in async_send_request().
109+
110+
111+
---
112+
113+
#### `borrow_loaned_request()`
114+
115+
```cpp
116+
agnocast::ipc_shared_ptr<RequestT> Client::borrow_loaned_request()
117+
```
118+
119+
Allocate a request message in shared memory.
120+
121+
| Template Parameter | Description |
122+
|-----------|-------------|
123+
| `RequestT` | Request message type (derived from `ServiceT::Request`). |
124+
| | |
125+
| **Returns** | Owned pointer to the request message in shared memory. |
126+
127+
128+
---
129+
130+
#### `get_service_name()`
131+
132+
```cpp
133+
char* Client::get_service_name() const
134+
```
135+
136+
Return the resolved service name.
137+
138+
| | |
139+
|-----------|-------------|
140+
| **Returns** | Null-terminated service name string. |
141+
142+
143+
---
144+
145+
#### `service_is_ready()`
146+
147+
```cpp
148+
bool Client::service_is_ready() const
149+
```
150+
151+
Check if the service server is available.
152+
153+
| | |
154+
|-----------|-------------|
155+
| **Returns** | True if the service server is available. |
156+
157+
158+
---
159+
160+
#### `wait_for_service()`
161+
162+
```cpp
163+
bool Client::wait_for_service(std::chrono::duration<RepT, RatioT> timeout) const
164+
```
165+
166+
Block until the service is available or the timeout expires.
167+
168+
| Parameter | Default | Description |
169+
|-----------|---------|-------------|
170+
| `timeout` | `std::chrono::nanoseconds(-1)` | Maximum duration to wait (-1 = wait forever). |
171+
| | | |
172+
| **Returns** | True if service became available, false on timeout. |
173+
174+
175+
---
176+
177+
#### `async_send_request()`
178+
179+
```cpp
180+
SharedFutureAndRequestId Client::async_send_request(agnocast::ipc_shared_ptr<RequestT> &&request, std::function<void(SharedFuture)> callback)
181+
```
182+
183+
Send a request asynchronously and invoke a callback when the response arrives.
184+
185+
| Template Parameter | Description |
186+
|-----------|-------------|
187+
| `RequestT` | Request message type (derived from `ServiceT::Request`). |
188+
| **Parameter** | **Description** |
189+
| `request` | Request from borrow_loaned_request(). Must be moved in. |
190+
| `callback` | Invoked with a SharedFuture when the response arrives. Call future.get() to obtain the response. |
191+
| | |
192+
| **Returns** | A SharedFutureAndRequestId containing the shared future (.future) and a sequence number (.request_id). |
193+
194+
195+
---
196+
197+
#### `async_send_request() [overload 2]`
198+
199+
```cpp
200+
FutureAndRequestId Client::async_send_request(agnocast::ipc_shared_ptr<RequestT> &&request)
201+
```
202+
203+
Send a request asynchronously and return a future for the response.
204+
205+
| Template Parameter | Description |
206+
|-----------|-------------|
207+
| `RequestT` | Request message type (derived from `ServiceT::Request`). |
208+
| **Parameter** | **Description** |
209+
| `request` | Request from borrow_loaned_request(). Must be moved in. |
210+
| | |
211+
| **Returns** | A FutureAndRequestId containing the future (.future) and a sequence number (.request_id). Call .future.get() to block until the response arrives. |
212+

‎docs/api/environment-variables.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
2+
# Environment Variables
3+
4+
<!-- Auto-generated — do not edit. Regenerate with: doxygen Doxyfile && python3 generate_api_reference.py -->
5+
6+
These environment variables configure Agnocast runtime behavior.
7+
8+
---
9+
10+
#### `LD_PRELOAD`
11+
12+
**Required.** Must include `libagnocast_heaphook.so` to route heap allocations to shared memory. Agnocast validates this at startup and exits with an error if missing.
13+
14+
Set it per-node in a launch file:
15+
16+
```xml
17+
<node pkg="my_package" exec="my_node" name="my_node" output="screen">
18+
<env name="LD_PRELOAD" value="libagnocast_heaphook.so:$(env LD_PRELOAD '')" />
19+
</node>
20+
```
21+
22+
---
23+
24+
#### `AGNOCAST_BRIDGE_MODE`
25+
26+
Controls the Agnocast–ROS 2 bridge mode for interoperability with standard ROS 2 nodes.
27+
28+
| Value | Description |
29+
|-------|-------------|
30+
| `0` or `off` | Bridge disabled. Agnocast topics are not visible to ROS 2 nodes. |
31+
| `1` or `standard` | **Standard mode (default).** Each Agnocast process runs its own bridge manager. |
32+
| `2` or `performance` | **Performance mode.** A single global bridge manager handles all bridging with pre-compiled plugins for lower overhead. |
33+
34+
Case-insensitive. Falls back to Standard mode with a warning if an unknown value is given.
35+
36+
```bash
37+
export AGNOCAST_BRIDGE_MODE=standard
38+
```
39+
40+
---
41+
42+
#### `AGNOCAST_BRIDGE_PLUGINS_PATH`
43+
44+
**Performance mode only.** Colon-separated list of additional search paths for bridge plugin shared libraries (`.so` files). If not set, plugins are searched in the default package install location.
45+
46+
```bash
47+
export AGNOCAST_BRIDGE_PLUGINS_PATH=/opt/my_plugins:/home/user/plugins
48+
```
49+

0 commit comments

Comments
 (0)