What is the C/C++ Driver, And How To Get It

The C/C++ driver, sometimes referred to as a “connector” or “client library,” is software that allows your C/C++ applications to talk to ScyllaDB clusters.

In this lesson, we’ll go over the driver, which is compatible with ScyllaDB and Cassandra, and see an example of how to use it to connect to a ScyllaDB cluster and perform basic operations.

Although written in C++, the driver exposes a C interface via functions and structures wrapped in extern “C”. The C language is not only fast, mature, and available on most platforms – it can also be called from other programming languages via C bindings. This means that once you master the driver’s API, you will be able to harness ScyllaDB’s high performance from a language of your choice on virtually any OS.

The C++ driver can be installed system-wide, from packages (*.deb, *.rpm), or built from the source code. In this lesson, we will briefly go through both possibilities. The code samples are marked as C++, but the only C++ specific functionality used is <iostream>, so you should have no problem with “porting” them to C.

The driver is already installed in the lab you will run below. To learn how to install it, see here.

The following sections explain the concepts and the code used; you will run the lab afterward.

Connecting to the Cluster

Let’s go over the code used to connect to the cluster we created. Y

As you can see, the C/C++ driver’s API often returns a pointer to CassFuture, which, roughly speaking, represents “a piece of information that doesn’t exist yet.” If you are not familiar with the concept of futures, it’s a powerful programming model that allows for efficient use of CPU, especially when I/O operations are involved.
However, to keep things simple, throughout this lesson, we will restrict the use of futures only to the blocking operations; that is, we will discard futures’ strongest point.

It’s easy to forget to free the allocated objects or leak them if an exception is thrown. In C++, it’s recommended that you automate their deletion with some implementation of “scope guard,” e.g., BOOST_SCOPE_EXIT or unique_ptr’s custom deleter. You can see this in /scylla-code-samples/cpp/part1/connect_unique.cpp:

Querying

In the example above, you might have noticed a “session” object. This will be the central object in our everyday work with the C/C++ driver. Under the hood, CassSession maintains per-node connections and a tunable pool of I/O threads to query according to the load-balancing policy. Because CassSession is thread-safe, it is generally recommended that you create one session per keyspace and share it among your application threads.

Let’s see how to read the mutant dataset we previously wrote. 

As you can see, CassResult consists of CassRows, and each CassRow consists of several CassValues. Rows and Values are just “views” into the cells of Result, and therefore their destruction is handled alongside the destruction of Result. In other words, we don’t have to free them in our code.

In the API reference, you will find all the functions that retrieve other data types from CassValue, such as int, float, UUID, collections, UDTs, etc. We can also run non-select queries in a blocking manner: add tables, insert or delete data, create users, alter keyspaces, drop indexes, … – all of that from C/C++, for example:

Iterators

Our query “SELECT […] FROM ks.mutant_data;” should have returned three rows, and we read only the first one. To iterate through all the rows, we will need – you guessed it – an iterator. Instead of calling cass_result_first_row(result) and retrieving a cell from it, we will traverse all the rows and access the first_name column in each of them. This code is from  /scylla-code-samples/cpp/part1/iterator.cpp.

Now that you understand the theory and how the code works, you can run the lab yourself.

Summary

In this lesson, we learned how to install and use the C++ driver to interact with a ScyllaDB cluster using an example. 

The driver exposes a C interface. It’s fast, mature, and available on most platforms. Using C bindings, it can be used with other programming languages on virtually any OS.