Creating a C API for a Rust library

Yoric has been doing great work porting Firefox’s client backend to Rust for use in Servo (see, so I decided to create a C API to allow using it from other contexts. You can observe the general direction of my problem-solving by looking at the resulting commits in the PR, but I drew a lot of inspiration from html5ever’s C API.

There are three main problems that require solving for any new C API to a Rust library:

  • writing low-level bindings to call whatever methods are necessary on high-level Rust types
  • writing equivalent C header files for the low-level bindings
  • adding automated tests to ensure that all of the pieces work

Low-level bindings:

Having never used before, I wrote my bindings by looking at the reference commit for integrating the library into Servo, as well as examples/ This worked out well for me for this afternoon hack, since I didn’t need to spend any time reading through the internals of the library to figure out what was important to expose. This did bite me later when I realized that the implementation for Servo is significantly more complicated than the example code, which caused me to redesign several aspects of the API to require explicitly passing around global state (as can be seen in this commit).

My workflow here was to categorize the library usage that I saw in Servo, which yielded three main areas that I needed to expose through C: initialization/shutdown, definition and recording of histogram types, and serialization. In each case I sketched out some functions that made sense (eg. count_histogram.record(1) became unsafe extern "C" fn telemetry_count_record(count: *mut count_t, value: libc::uint)) and wrote placeholder structures to verify that everything compiled.

Next I implemented type constructors and destructors, and decided not to expose any Rust structure members to C. This allowed me to use types like Vec<T> in my implementation of the global telemetry state, which both improved the resulting API ergonomically (many fewer _free functions are required) and allowed me to write more concise and correct code. This decision also allowed me to define a destructor on a type exposed to C; this would usually be forbidden due to changing the low-level representation of the type in ways visible to C if the structure members were exposed. Generally these API methods took the form of the following:

pub unsafe extern "C" fn telemetry_new_something(telemetry: *mut telemetry_t, ...) -> *mut something_t {
    let something = Box::new(something::new(...));

pub unsafe extern "C" fn telemetry_free_something(something: *mut something_t) {
    let something = Box::from_raw(something);

The use of Box in this code places the enclosed value on the heap, rather than the stack, which allows us to return to the caller without the value being deallocated. However, because C deals in raw pointers rather than Rust’s Box type, we are forced to convert (ie. reinterpret_cast) the box into a pointer that it can understand. This also means that the memory pointed to will not be deallocated until the Rust code explicitly asks for it, which is accomplished by converting the pointer back into an owned Box upon request.

Once I had meaningful types, I filled out the API methods that were used for operating on them. The types used in the public API are very thin wrappers around the full-featured Rust types, so the step was mostly boilerplate like this:

pub unsafe extern "C" fn telemetry_record_flag(flag: *mut flag_t) {

The code for serialization was the most interesting part, since it required some choices. The Rust API requires passing a Sender<JSON> and allows the developer to retrieve the serialized results at any point in the future through the JSON API. In the interests of minimizing the amount of work required on a Saturday afternoon, I chose to expose a synchronous API that waits on the result from the receiver and returns the pretty-printed result in a string, rather than attempting to model any kind of Sender/Receiver or JSON APIs. Even this ended up causing some trouble, since supports stable, beta and nightly versions of Rust right now. Rust 1.5 contains some nice ffi::CString APIs for passing around C string representations of Rust strings, but these are named differently in Rust 1.4 and don’t exist in Rust 1.3. To solve this problem, I ended up defining an opaque type named serialization_t which wraps a CString value, along with a telemetry_borrow_string API function to extract a C string from it. The resulting API works across all versions of Rust, even if it feels a bit clunky.

C header files

The next step was writing a header file that matched the public types and functions exposed by my low-level bindings (like an inverse bindgen). This was a straightforward application of writing out function prototypes that match, since all of the types I expose are opaque structs (ie. struct telemetry_t;).

The most interesting part of this step was writing a C program that linked against my Rust library and included my new header file. I ported a simple Rust test from one I added earlier to the low-level bindings, then wrote a straightforward Makefile to get the linking right:

CC ?= gcc
CFLAGS += -I../../capi/include/
LDFLAGS += -L../../capi/target/debug/ -ltelemetry_capi
OBJ := telemetry.o

%.o: %.c
	$(CC) -c -o $@ $< $(CFLAGS)

telemetry: $(OBJ)
	$(CC) -o $@ $^ $(LDFLAGS)

This worked! Running the resulting binary yielded the same output as the test that used the C API from Rust, which seemed like a successful result.

Automated testing

Following html5ever's example, my prior work defined a separate crate for the C API (libtelemetry_capi), which meant that the default cargo test would not exercise it. Until this point I had been running Cargo from the capi subdirectory, and running the makefile from the examples/capi subdirectory. Continuing to steal from html5ever's prior art, I created a script that would run the full suite of Cargo tests for the non-C API parts, then run cargo test --manifest-path capi/Cargo.toml, followed by make -C examples/capi, and made Travis use that as its script to run all tests.

These changes led me to discover a problem with my Makefile - any changes to the Rust code for the C API would not cause the example to be rebuilt, so I didn't actually have effective local continuous integration (the changes still would have been picked up on Travis). Accordingly, I added a DEPS variable to the makefile that looked like this:
DEPS := ../../capi/include/telemetry.h ../../capi/target/debug/libtelemetry_capi.a Makefile
which causes the example to be rebuilt any time any of the C header, the underlying static library, or the Makefile itself are changed. The result is that whenever I'm modifying, I can now make changes, run ./ and feel confident that I haven't inadvertently broken the C API.

You are receiving this mail because you are mentoring this bug

Good news! As of today, Bugzilla now sends out emails containing both an X-Bugzilla-Mentors header and a “You are mentoring this bug” message. This means that it’s now possible to highlight activity in your mentored bugs in your favourite email client! I use Gmail, so I’ve created a filter that searches for “You are mentoring this bug” and stars it; you might consider the same, or giving it a label so it’s easy to see at a glance if there’s something you should prioritize. For mail header filters, you’ll want to search for X-Bugzilla-Mentors containing your bugzilla email address.

Note: this only works if searching for the mentor tag in the whiteboard yields a unique result. If the tag reads mentor=ashish and there’s an another account with :ashish_d, the result will not be unique so no relevant header value or footer will be applied to any messages sent to Ashish.

Please make use of this! There is no longer a good excuse for questions in mentored bugs to go unanswered or overlooked; let’s make sure we’re providing the best possible mentoring experience to new contributors that we can.

Taking a page from roc’s book


Next steps for Bugs Ahoy: patches desired!

Bugs Ahoy is coasting along right now, and that’s fine. It fills a need, and apparently it does that pretty well from what I hear. However, there is a greater need – Mozilla needs a task board for all activities, and we need to not be distracted by reinventing yet another system. I’m kicking off a project to expand the Bugs Ahoy project to fill this need, and I am need lots of help.

Here’s the plan:

  • The task board will scrape data from an empty github repository’s issues list
  • These issues will be tagged in broad, useful ways (marketing, design, writing, mozilla hispano, whatever)
  • New contributors with skills other than writing code will be able to browse the tasks available and get involved easier and quicker than ever before!

The main work that needs to be done falls into two categories:

  • Authenticating with github (please help, my brain just falls apart when I try to read about OAuth)
  • Creating a page that allows creating new tasks/modifying existing ones through the Github API

We want to avoid any need for users of the task board (both task creators and browsers) to ever visit Github; it’s just serving as a convenient backend to store the data. I’m snowed under with too many projects right now and can’t focus on this right now, but I would be thrilled to work with someone (or several someones!) to get it done. This is going to be a very useful tool when it’s finished, we just need some elbow grease to crank out a prototype. If you have experience with Javascript and/or Python, please get in touch! You can find the source on github.

Numbers rule the world

One thing that has become clear in my work as a Firefox coding steward is that we have no idea how healthy our community is. When people ask me how many unpaid contributors we have, I don’t have an answer I can give them. The corollary to this is that any attempts to change our contributor engagement processes will be complete shots in the dark, with us fumbling to discover what kind of effect our changes cause. David Eaves underlined this message in the community building workshop yesterday, so I decided to do something about it.

Measuring the size of a whole community is hard, so I’m not tackling that problem yet. Instead, I’ve focused on the problem of making first-time contributions more visible, and measuring the rate of incoming new contributors in a methodical way. I decided to extract the commit data of mozilla-central into a database which I could query in useful ways; in particular I store a table of committers that includes a name, email address, number of commits, date of first commit, and date of last commit. You can see the raw results of my work at my github repository, where I’m banging away at multiple tools that use this data in different ways.

Tool the first – the Firefox coding community health report:

This measures the number of first patches that are committed in any given month. This graph allows us to see how effective we are at shepherding new contributors through the process of shipping their first change to the code.

Tool the second – the first-time contributor awareness raiser:

This tool lists the contributors whose first patch was committed in a given period of time. With this, we can create reports that will allow us to take actions that celebrate this accomplishment (blog posts, swag, announcements in meetings, submissions for about:credits, etc.). This will allow us to take the burden of these tasks off of the engineers who can’t see beyond the patch, and place it in the hands of people who have a broader vision of building community effectively.

I’m not finished yet! I’m also really interested in measuring how many contributors drop off in a given month – by combining this with the incoming contributor data, we can get rough data about churn in the community, and compare how many people are leaving vs. how many newcomers we have. There are many more interesting measurements to be taken here, and I’m excited to be digging into this data. Feel free to join me! The github repo contains the script to create the database from the git mozilla-central repository, and you’re welcome to explore the data with me.

Help wanted: using the github API with authentication

Bugs Ahoy retrieves issues from Github for certain categories (such as B2G and Test Automation). Unfortunately, I learned recently that unauthenticated API users are now limited to 60 requests an hour, and that means that these categories often end up broken. I really want to fix this by being an authenticated user, but OAuth scares me. I would dearly appreciate someone fearless to help me get my github authentication ducks in a row so new contributors can see the full range of bugs available to them. Bugs Ahoy is entirely a client-side app written in HTML/CSS/JS, so bear that in mind when volunteering. Thanks in advance!

Private Browsing and You

Hello everyone, it’s your resident Private Browsing developer here! I’ll state it up front – the release of 15.0.1 was triggered by code I wrote that broke private browsing mode in significant, privacy-affecting ways. Ehsan and I fixed that for 15, 16, and 17 by backing out the problem code completely, but we’ve been working hard to fix it properly in Firefox 18 (currently in Nightly). This means that we want YOUR help to ensure that we haven’t subtly broken private browsing mode in nightly, and here’s how you can do that:

Take some time every day to clear your disk cache, then put your browser into private browsing mode. If you want to use it for traditionally-private things, that’s cool, it just may be slightly more embarrassing to thoroughly report bugs you encounter. What would be very helpful is if you could spend some time using your browser for regular, non-private things, and every so often open up about:cache and look through the entries in your disk cache. If you see any entry that looks like it came from one of the sites you were visiting, file a bug and CC :jdm and :ehsan. In fact, I will even accept comments on this post, or IRC pings, or emails, or whatever – these are important privacy failures that need to be addressed before FF 18 goes out the door. Do your part to make it unremarkable!

Get your project listed in!

Back in June I created the slightly-misnamed What Can I Do For Mozilla tool (misnamed since it only focuses on code that needs writing, ignoring any other useful skills). It took off all over twitter, but I never actually formally announced it. Now, needs your help! I want to fill it with as many projects and teams as I can, since I link an average of 250 people to it every month. Is your project missing from it? Find me and let me know, or (even better), file a pull request. The format for adding a new entry is really simple:  

<li target="">Popcorn
  <div class="extra">create interactive media pages that seamlessly integrate video, audio, and traditional web technologies</div>

All I ask is that you link to a document that has some kind of instruction for how to get involved. That’s it!

Things I want someone to create for me, volume 1

A mechanism that automatically expands all collapsed merges in a pushlog view. I don’t care if it’s a Firefox extension or modification to the pushloghtml source that adds an expand=1 parameter to the query string; I am tired of manually expanding each one.

Sometimes I do other things than write code

I don’t always write code, but when I do… no wait, that’s not right. Here’s what I’ve been up to in the past week:

I sing in the an all-male university a capella group called The Water Boys. Our end of term concert is happening on Sunday, and the overall club EOT concert just occurred last weekend:

I also sing in a barbershop quartet called the Bearded Baritones, which doesn’t allow me to hide in the background nearly as much as the 17 person group does (third from right, if curious):

Having just attended my last class of my university career (assuming exams go well), I have to say that this is one aspect of the past five years that I will miss dearly when I move to Toronto this summer.