yurii.
← back to work
CASE STUDY

JNI library on Android

SHIPPED
Started: Aug 2026Shipped: Sep 2026Role: Architect and Lead Engineer

JNI without the boilerplate: what I learned building a layer over it

I started with a plain question: where do I keep a C++ object between calls from Kotlin? I ended up writing a small library that sits on top of JNI. This is not a post about the library. That comes later. This is about the problems I ran into, the decisions I took, and what I would check first if I were you.

Why I needed JNI at all

The idea was a library for IP cameras. Not a big idea, honestly. We needed one feature: work with a lot of cameras and switch between the sub stream and the main stream of a camera.

I looked for an existing library that supports many camera vendors, is free, and has an open source license. I couldn't find a normal one. So the decision was to write it.

Writing it meant not writing it in Kotlin. Some cameras give 4K, and we need to show several of them at the same time. That needs direct access to memory and fast execution, and that is C++. JNI is what connects the C++ code to the API the library gives to the end user.

I had worked with a JNI layer before, and I remember how hard it was. You write a pile of instructions to turn one field into another, one class into another, to call each method, to return callbacks. Callbacks were a real mess. You have to remember to free memory, you can't overload memory in loops, you have to clean up objects every time. And this code never gets smaller. It grows with every method. On top of that, errors: you have to check every exception, and the errors themselves look strange.

So I decided I wasn't doing it like this again. I wanted a layer that does it by itself: allocates and frees memory, registers subscribers, registers callbacks, deals with the ProGuard rules.

What already exists

I have to be honest about this part. I didn't look. I found out only recently that a library very close to what I built already exists: Facebook's fbjni. I had spent a lot of time by then. That one hurt.

So this isn't a comparison I made before starting. It's what I know after. The fbjni README shows a C++ struct that describes a Java class, descriptors worked out by the compiler, references managed for you, exceptions translated both ways. That is close to what I wanted. Its quick reference also lists strings, arrays, collections, direct ByteBuffer and "hybrid" objects that hold C++ state. I didn't find in the documentation anything about what close() should do while another thread is inside the object, or about who runs a callback and on which thread. I haven't read the source and I haven't used it, so I'm not saying it can't. I'm saying I didn't find it. A proper comparison belongs in the post about my library.

Where it actually hurts

For me the worst part of JNI is the boilerplate. Not that any single piece is hard. It's boring to write, you can make a mistake in it, and then you debug it. That is the real cost.

What decides whether a native layer survives in production is two things: memory and threads. Those are where people go wrong most often, so most of this post is about them.

The reason is that there are two directions of call, and they are not the same problem.

When Kotlin calls in, the JVM gives you everything. When C++ calls out from its own thread, you have to build every guarantee yourself.

Memory

A reference in JNI isn't the object. It is a handle that the JVM treats as a garbage collector root. There are three kinds, and each fails in its own way.

ReferenceLivesHow it goes wronglocaluntil the native function returns, one thread onlythe table is small, about 512 entries on ART. A loop that doesn't delete overflows it. On a native thread nobody ever frees them.globaluntil you delete it, any threadforgot to delete: the object lives forever.weak globaluntil the object is collected"check that it is alive, then use it" leaves a gap in which it can be collected.

What I wanted was for the type to say who owns the reference, so I don't have to remember. In C++ that is RAII: an object whose destructor does the cleanup, like use {} in Kotlin. The library has LocalRef, GlobalRef and WeakGlobalRef. They can be moved but not copied, because two owners of one reference would delete it twice. If the compiler says the copy is deleted, it's asking who owns this now.

A few details came out of this that I wouldn't have guessed:

  • A weak reference can't be asked "are you alive?". The only operation is promote(), which gives a local reference or an empty one, so there is no gap.
  • GlobalRef doesn't go in a static variable. Static destructors run during exit(), when the VM may already be going away, and DeleteGlobalRef there crashes the process on its way out.
  • A LocalRef keeps the env of the thread that made it. Its destructor must not call for a new env, because after a detach that would attach the thread again.
  • A native object points back to its Kotlin owner weakly. If it holds the owner strongly, the pair forms a cycle through a GC root and neither is ever collected. Same as a ViewModel holding an Activity.

On the garbage collector: every global reference is a root, so it keeps its object, and everything that object references, alive. That is the cost of a listener held strongly, and it's why the type says it. The other direction is memory the collector can't see at all. I come back to that below.

Threads

A JNIEnv* belongs to one thread. You can't pass it to another one, and you can't keep it in a field. When I first read this my reaction was: so, there's a small problem, we need to design something so that access from different threads is painless. I'll be honest that I'm not sure I still hold every detail in my head. Here's the design.

Only the JavaVM* is cached. It's the same for the whole process. The env for the current thread is looked up each time, and GetEnv is cheap.

Three decisions here:

  • Detach only what we attached. A thread that someone else attached stays attached after our call.
  • Attach with the real thread name, so the thread shows up in ANR traces and in the profiler as camera-rx and not as Thread-12.
  • If attach fails, crash with a clear message. There is nothing sensible to do next.

FindClass on a native thread sees only system classes, because the thread has no app class loader. So classes and methods are looked up once, at startup, never in a hot path.

Startup, and the strings I hated

Raw JNI wants a signature string like "(Ljava/lang/String;I)V" for every method. They aren't hard, but I had to keep those codes in my head, and the syntax is awful. One wrong letter and you find out at runtime.

So signatures are built by the compiler from C++ types. A type that has no Java equivalent doesn't compile: bool isn't jboolean, and a bare jobject doesn't say which class it is. You describe a Kotlin class once, and from then on you call it like a C++ class.

// camera/bindings: a plain C++ function. Strings, optionals and lists are converted for you.
std::string redactUrl(JNIEnv *, jclass, const std::string &url) { return camera::redactUrl(url); }

The other half is what happens when something is missing. I decided that if something is missing at startup, the app should fail, right there. A missing method means the programmer made a mistake or forgot something, and we must tell them clearly. A compile error would be nicer, but we can't have one: we can't walk the graph of what's registered at compile time, and it would be very hard to do. So the one simple way is to go through everything that is registered and everything that isn't, at launch, and say it plainly. The check collects every problem, writes each one with the exact name, and only then returns JNI_ERR. It's at startup, so it's far more useful than a crash on the first call.

Errors: whose fault is it?

My first design for errors was big. Errors built on std::error_code, a result type of its own, macros to unwrap it, a global switch that changed how checks behaved. I read it and understood almost nothing. I said that to me this looked like Elvish, and that I had a feeling it wasn't thought through cleanly. When we looked again, there were two ways to report one error, five macros and a global setting. None of it was needed.

What helped was to stop talking about syntax and ask one question. When something goes wrong, whose fault is it?

The third case I didn't get at first. It is our own bug inside the native code, the "this cannot happen". The caller did everything right and nothing outside can fix it. You can only crash, before the bad state spreads.

For the first case I said the app should crash at once, and that raised a question: with what? A native abort gives a C++ stack that doesn't show which Kotlin line passed -1. An IllegalArgumentException also kills the app if nobody catches it, and its stack points at the exact Kotlin line, the way require() does. The answer was one set of macros for both worlds. The wrapper around every native function turns the C++ exception into the Kotlin one. If the call was pure C++, nobody catches it and the process dies with a tombstone.

Errors that the world causes are flat: a domain, a code and a message. No class hierarchy, because a hierarchy would mean generating Java classes for every code. A code 1 in one library never meets a code 1 in another. I also didn't want a long when over many codes in app code, so every error carries a kind: Transient, NeedsUser or Fatal. The app looks at the kind first, and at the exact code only when it needs a special reaction.

One more thing the review found. The error class derived from std::exception and held a std::string. Copying an exception isn't allowed to throw, but copying a string can, if memory runs out, and then the program ends in std::terminate. Basing the class on std::runtime_error makes the copy safe.

Who owns the native object

The classic trick is to create the object in C++, cast the pointer to a long, return the long to Kotlin, and cast it back on every call. When I first saw it my reaction was, how does this even work. It works. I just didn't like it.

My complaint, at first, was debugging. You stop on a breakpoint, open a Kotlin object, and there's a long in it. A pointer? A reference? Some id? You can't tell what's behind it, you read comments, and then you open the C++ code. A field that you can only understand by reading another language is a bad field.

Then the crash. You want to close the object, you free the memory, and the app dies, not always and not on the line you just wrote.

The reason is that there are two objects with two lifetimes. The Kotlin one lives in the JVM. The native one lives in the native heap, and nobody looks after it unless you do. close() on the Kotlin side only sees a number.

The caller does thisThe raw pointer does thisstart() after close()reads freed memoryclose() twicefrees twiceclose() while another thread readsdeletes the object under the running readnever calls close()the socket lives as long as the process

So I stopped giving Kotlin an address. The library keeps a table, Kotlin gets a number, and every call looks the number up. A closed or unknown number is an IllegalStateException, not a crash. The counter starts at 1 and never goes back, so an old number can't mean a different object later. The table holds the object in a shared_ptr, and each running call holds one too, so close() in the middle can't pull the object from under a call.

Now close() is safe but useless. Say a thread is blocked in recv() inside the object. It holds a reference, so the object is alive, so the socket is open, so recv() keeps blocking.

My rule is this: when you call close() you expect the resource to be freed right now, not when the last call finishes. For a camera that's obvious. I think many people writing code today, with or without help from a tool, miss this. A resource that is "closed" in a year and a half isn't closed.

The C++ class gets an onClose() hook that close() calls at once. It runs while other threads are still inside the object, so it can't wait for anything. It sets a flag, shuts the socket down and wakes the sleepers. The memory goes later, when the last call is done. Two rules follow for whoever writes the class: use shutdown(fd) in the hook and close(fd) only in the destructor, otherwise the system can hand the same descriptor number to another file while a thread still reads the old one; and the object's own worker thread must not hold a shared_ptr to the object, or the destructor ends up joining its own thread.

I'll also say what isn't there. Some tasks want a close that waits for the work in progress. Looking back, I should have split it in two, a close() that frees now and a separate "await close" or a forced one. The library has only the first today.

Callbacks: when native code calls you

A callback means C++ calls Kotlin on a thread of its own, and every guarantee from the first diagram is gone.

The first draft of the design said native code should hold the listener weakly. It sounded careful. I think it was wrong, and what I'd say is what I said when I came back to it: as long as there is a subscriber, we have to notify it. If the system clears the reference, the listener waits for an event and then never gets one. A lambda passed to subscribe { ... } is referenced by nobody else, the collector takes it, and the events silently stop. SharedPreferences listeners have this trap. The design was changed before any callback code: native code holds the listener strongly while the subscription is open. The price is the usual one, a listener that captures an Activity keeps it alive until the subscription is closed.

The second decision is about threads. A subscription takes an Executor, with no default. The callback never runs on the camera's thread, where user code could block the stream or close the camera from inside its own callback.

Then memory the collector can't see. A ByteBuffer over native memory doesn't tell the collector how big the memory behind it is. A frame of a megabyte looks like a tiny object. If a slow listener makes the queue drop frames, they can pile up in native memory before the collector decides to run. This was written down as a risk during the design review, and I said callbacks were too critical a part of the foundation to leave it at a note, so it was measured. In a test with frames of 1 MiB and a slow consumer on a small Java heap, native memory grew to 3000 MiB. The fix is small: the runtime counts the bytes of live native buffers, and above 64 MiB asks for a collection, at most every 200 ms. The same test then peaks at 83 MiB. That is a host test with simulated frames, not a phone, and what System.gc() costs on Android hasn't been measured.

A slow consumer also needs a policy, and it isn't the source's business: keep everything in order, keep only the latest event (video wants this), or keep the last N and drop the oldest.

Release builds

R8 looks at Kotlin and Java code. It can't see that a C++ function looks up a class by name, so it removes or renames exactly what only native code uses. I've had this happen more than once, in two companies. [YURII: one concrete case here if you remember one.]

What does the error look like on the C++ side? There is no "symbol not found" in C++. JNI returns NULL and leaves a Java exception pending.

Native code does thisR8 removed...What happensFindClassthe classNULL, NoClassDefFoundError pendingGetMethodIDthe methodNULL, NoSuchMethodError pendingGetFieldIDthe fieldNULL, NoSuchFieldError pendinga native found by namethe nameUnsatisfiedLinkError on first call

If you don't check, the next line uses NULL and the app crashes far from the cause. That is why everything is looked up at startup and every missing name is reported. A wrongly minified build then tells you the exact class at launch. That check exists and is tested on the host. An instrumented test on a minified build is still not done.

What I would throw away on day one

  • A pointer in a long. Give Kotlin a number that native code can refuse.
  • finalize(). It runs on a finalizer thread, in no order, and a watchdog can kill the app. Use Cleaner or a PhantomReference as a safety net, and make close() the real mechanism.
  • Signature strings written by hand.
  • JNIEnv* kept in a field.
  • A weak reference to a listener.
  • Many small calls across the border. A number costs nothing, a string is a copy, a list costs a call per element, so make fewer, bigger calls.
  • A separate .so per library. Two copies of the runtime in one process each had their own state and their own startup, and I saw the startup log twice. One .so, one JNI_OnLoad.

Where I would start

With the same thing I did: the fundamentals. How the JNI env works. How pointers and references work, local and global. How the env is passed around, and how classes and methods are found. Before any helper library, you need that picture, because every bug later comes from one of those places.

Then think hard about memory: how objects are created, how they're cleaned up, what each one costs, what load the garbage collector carries, what lands in native memory that nobody sees. Use RAII, and count local references. And think hard about threads, which is the other area where most mistakes happen.

Last, if the library is going to be public, think about the developer who uses it. The whole point is to remove boilerplate, so every piece of ceremony you leave in is a place where they can make a mistake.

Where it stands

I've started using the library in my camera library. So far it flies: callbacks and object registration are connected and working, with no problems yet. Most of the functionality isn't connected there yet.

The library is here:

GitHub - yuriisurzhykov/jni-runtime: A foundational project for every JNI projectsgithub.com · GitHub(opens in a new tab)

It will be the topic of the next post, and the project has its own section.

Stack

KotlinJNI & C++C++Android NDK