Skip to content

Commit 2b66272

Browse files
shuangelashuangela
authored
DOCSP-48179 add async c driver page (#90)
* add async c driver page * change title * revert wording * fix bulleted list * fix vale error * move c code to seperate file * fix include * rm edits * fix typo * rb feedback
1 parent 5717c5c commit 2b66272

File tree

3 files changed

+132
-0
lines changed

3 files changed

+132
-0
lines changed

‎source/async-c-driver.txt

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
.. _c-async-driver:
2+
3+
==============================
4+
Async C Driver: Public Preview
5+
==============================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: amongoc, async, preview, asynchronous, prototype
19+
20+
We are excited to share the release of a new prototype that could reshape how
21+
C developers interact with MongoDB: the ``amongoc`` library. This experimental driver
22+
leverages the power of asynchronous programming to offer an efficient, non-blocking
23+
interface for MongoDB operations. Although still in public preview and not yet ready
24+
for production, your feedback will play a crucial role in shaping the future direction
25+
of this project.
26+
27+
28+
What is amongoc?
29+
----------------
30+
31+
``amongoc``, short for "asynchronous MongoDB C driver," is designed for developers
32+
who need a performant, asynchronous client library for MongoDB. It implements a selected
33+
subset of MongoDB driver APIs to provide a sneak peek into what a C-based asynchronous
34+
client might look like. By evaluating this prototype, developers can help us gather
35+
critical insights that could influence the development of a production-ready solution
36+
in the near future.
37+
38+
Why Go Asynchronous?
39+
--------------------
40+
41+
The motivation for building ``amongoc`` is rooted in performance optimization and
42+
providing high concurrency. Asynchronous programming decouples the initiation of a
43+
task from its continuation, addressing the inefficiencies of synchronous operations,
44+
particularly I/O, which are inherently slow and can block other processes.
45+
Asynchronous programming allows applications to remain responsive while waiting for
46+
I/O operations to complete, making it ideal for high-performance, network-intensive
47+
use cases. ``amongoc`` will also facilitate the integration of MongoDB into asynchronous
48+
frameworks like Drogon. Notably, it has also been the `top requested feature <https://feedback.mongodb.com/forums/924286-drivers/suggestions/47080057-asynchronous-variant-of-mongodb-c-driver>`__ for the
49+
C driver by users.
50+
51+
Getting Started with amongoc
52+
----------------------------
53+
54+
To explore ``amongoc``, visit the `GitHub repository <https://github.com/mongodb-labs/mongo-c-driver-async/>`__
55+
and access our comprehensive `Documentation <https://mongodb-labs.github.io/mongo-c-driver-async/>`__.
56+
Our resources include:
57+
58+
- A step-by-step `Quickstart guide <https://github.com/mongodb-labs/mongo-c-driver-async/tree/develop/etc/quickstart>`__
59+
to help you set up and initiate your first connection.
60+
- Detailed `Reference documentation <https://mongodb-labs.github.io/mongo-c-driver-async/ref/>`__
61+
covering the configuration, building, and usage of the library.
62+
- `Tutorials <https://mongodb-labs.github.io/mongo-c-driver-async/learn/>`__ to walk you through
63+
common use cases and showcase the potential of asynchronous operations.
64+
- A list of `amongoc features <https://mongodb-labs.github.io/mongo-c-driver-async/ref/features/>`__
65+
- Descriptions of `amongoc’s design considerations <https://mongodb-labs.github.io/mongo-c-driver-async/explain/consider/>`__
66+
and `amongoc’s asynchrony model <https://mongodb-labs.github.io/mongo-c-driver-async/explain/async-model/>`__
67+
68+
The following example is an application that initializes an asynchronous event loop and attempts to establish a connection to a local MongoDB server using the ``amongoc`` library:
69+
70+
.. literalinclude:: /includes/async-c-driver-example.c
71+
:language: c
72+
:dedent:
73+
74+
Feedback: Your Voice Matters
75+
----------------------------
76+
77+
This public preview release is focused on gathering user feedback to inform the architectural
78+
decisions for a production-ready version of ``amongoc``. We invite you to share your thoughts and
79+
suggestions in GitHub `discussions <https://github.com/mongodb-labs/mongo-c-driver-async/discussions>`__
80+
and `issues <https://github.com/mongodb-labs/mongo-c-driver-async/issues>`__. We are especially
81+
interested in your opinions about the interface, and the build and runtime requirements. Our goal
82+
is to collect as much user input as possible to align with the needs and expectations of our user community. Your feedback is invaluable, and we eagerly look forward to hearing from you and seeing what you'll create with ``amongoc``!

‎source/includes/async-c-driver-example.c

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
#include <amongoc/amongoc.h> // Make all APIs visible
2+
3+
#include <stdio.h>
4+
#include <stdlib.h>
5+
6+
amongoc_box on_connect(amongoc_box userdata, amongoc_status *status, amongoc_box result);
7+
8+
int main(void)
9+
{
10+
amongoc_loop loop;
11+
amongoc_status status = amongoc_default_loop_init(&loop);
12+
amongoc_if_error(status, msg)
13+
{
14+
fprintf(stderr, "Failed to prepare the event loop: %s\n", msg);
15+
return 2;
16+
}
17+
18+
// Initiate a connection
19+
amongoc_emitter em = amongoc_client_new(&loop, "mongodb://localhost:27017");
20+
// Set the continuation
21+
em = amongoc_then(em, &on_connect);
22+
// Run the program
23+
amongoc_detach_start(em);
24+
amongoc_default_loop_run(&loop);
25+
// Clean up
26+
amongoc_default_loop_destroy(&loop);
27+
return 0;
28+
}
29+
30+
amongoc_box on_connect(amongoc_box userdata, amongoc_status *status, amongoc_box result)
31+
{
32+
// We aren't using the userdata for this example.
33+
(void)userdata;
34+
// Check for an error
35+
amongoc_if_error(*status, msg)
36+
{
37+
fprintf(stderr, "Error while connecting to server: %s\n", msg);
38+
}
39+
else
40+
{
41+
printf("Successfully connected!\n");
42+
amongoc_client *client;
43+
amongoc_box_take(client, result);
44+
// `client` now stores a valid client. We don't do anything else, so just delete it:
45+
amongoc_client_delete(client);
46+
}
47+
amongoc_box_destroy(result);
48+
return amongoc_nil;
49+
}

‎source/index.txt

+1
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
:titlesonly:
77
:maxdepth: 1
88

9+
Asynchronous C Driver: Public Preview </async-c-driver>
910
Get Started </get-started>
1011
Connect to MongoDB </connect>
1112
Databases & Collections </databases-collections>

0 commit comments

Comments
 (0)