Connecting to a MongoDB Server

This page will show how to asynchronously connect to a MongoDB server from a C program.

Including the amongoc APIs

To make all amongoc APIs visible, include the everything-header:

Headers

#include <amongoc/amongoc.h>  // Make all APIs visible

#include <stdio.h>
#include <stdlib.h>

Creating an Event Loop

The first thing to do before connecting to a program is to create an event loop. amongoc includes a basic default single-threaded event loop suitable for basic programs:

Create a default event loop

int main(void) {
    amongoc_loop   loop;
    amongoc_status status = amongoc_default_loop_init(&loop);
    amongoc_if_error (status, msg) {
        fprintf(stderr, "Failed to prepare the event loop: %s\n", msg);
        return 2;
    }

Creating a Client

A client is created and initialized asynchronously and is associated with an event loop, done using amongoc_client_new():

Create a client emitter

amongoc_emitter em = amongoc_client_new(&loop, "mongodb://localhost:27017");

Hint

The URI string above is a simple default for a locally-running server without TLS enabled. You should replace it with your own if your URI is running in a different location.

Create the Continuation

An amongoc_emitter object is not a client. Rather, it is an object that represents an asynchronous operation. To get the client, we need to attach a continuation:

Continuation prototype

amongoc_box on_connect(amongoc_box userdata, amongoc_status* status, amongoc_box result);

Attach the continuation with amongoc_then()

em = amongoc_then(em, &on_connect);

The continuation function on_connect looks like this:

Continuation

amongoc_box on_connect(amongoc_box userdata, amongoc_status* status, amongoc_box result) {
    // We don't use the userdata
    (void)userdata;
    // Check for an error
    amongoc_if_error (*status, msg) {
        fprintf(stderr, "Error while connecting to server: %s\n", msg);
    } else {
        printf("Successfully connected!\n");
        amongoc_client* client;
        amongoc_box_take(client, result);
        // `client` now stores a valid client. We don't do anything else, so just delete it:
        amongoc_client_delete(client);
    }
    amongoc_box_destroy(result);
    return amongoc_nil;
}

Create the Operation State

When we are done defining the entire asynchronous control flow, we need to convert the amongoc_emitter to an operation and enqueue it with the event loop. There are several ways to do this, but the simplest is amongoc_detach_start():

Launch the operation

amongoc_detach_start(em);

This will enqueue the associated program with the event loop, and will automatically release resources associated with the operation when the operation completes.

Note

amongoc_detach_start() will “consume” the emitter object. The em emitter object is “poisoned” and cannot be manipulated further.

Run the Program

The amongoc_detach_start() call only enqueues the operation, but does not execute it. We need to actually give control of the main thread to the event loop. This is done using amongoc_default_loop_run():

Run the program

amongoc_default_loop_run(&loop);

Clean up the Event Loop

After amongoc_default_loop_run() returns, there is no more pending work in the event loop, so we are done. Before returning, we need to destroy the event loop object:

Destroy the event loop

amongoc_default_loop_destroy(&loop);

The Whole Program

Here is the complete program:

connect.example.c

#include <amongoc/amongoc.h>  // Make all APIs visible

#include <stdio.h>
#include <stdlib.h>
// end:headers

amongoc_box on_connect(amongoc_box userdata, amongoc_status* status, amongoc_box result);

int main(void) {
    amongoc_loop   loop;
    amongoc_status status = amongoc_default_loop_init(&loop);
    amongoc_if_error (status, msg) {
        fprintf(stderr, "Failed to prepare the event loop: %s\n", msg);
        return 2;
    }

    // Initiate a connection
    amongoc_emitter em = amongoc_client_new(&loop, "mongodb://localhost:27017");
    // Set the continuation
    em = amongoc_then(em, &on_connect);
    // Run the program
    amongoc_detach_start(em);
    amongoc_default_loop_run(&loop);
    // Clean up
    amongoc_default_loop_destroy(&loop);
    return 0;
}

// on_connect def
amongoc_box on_connect(amongoc_box userdata, amongoc_status* status, amongoc_box result) {
    // We don't use the userdata
    (void)userdata;
    // Check for an error
    amongoc_if_error (*status, msg) {
        fprintf(stderr, "Error while connecting to server: %s\n", msg);
    } else {
        printf("Successfully connected!\n");
        amongoc_client* client;
        amongoc_box_take(client, result);
        // `client` now stores a valid client. We don't do anything else, so just delete it:
        amongoc_client_delete(client);
    }
    amongoc_box_destroy(result);
    return amongoc_nil;
}
// on_connect end