Chapter 5: A fabulous FFI cookbook
The chapter introduction frames a recipe-book library as a small, reliable solution to a time-pressed programming assignment.
After this chapter you will be able to
- Compromise in library design. Explain why programmers make compromises and how that pressure shapes the recipe-book assignment: deliver a small, reliable library for Tony’s frontend without doing unnecessary work.
- Audience driven library design. Explain how Tony’s application, skills, and time constraints shape the decision to provide a Zig library that his PHP application can use.
- Recipe book API surface. State the operations the agreed library surface needs to provide.
- C ABI as common tongue. Explain that the Zig library’s functions need to be compatible with the C ABI so they can communicate with Tony’s PHP, because many languages use the C ABI as a common interface.
- ABI rules for compatibility. Explain that an ABI is a set of rules for interaction between compiled binaries, including conventions for function calls, data layout, and the stack. Describe why shared rules let code from different languages and compilers work together.
- System-specific C ABI. Explain why there is no single C ABI for every computer and why C provides a useful common denominator for binary compatibility.
- C-Compatible Structs and Exports. Explain how `extern struct` gives a Zig struct a C-compatible layout and how `export` makes C-compatible declarations available when building a library.
- Pointers Across the ABI. Explain how pointers allow a C-ABI-compatible interface to refer to data structures that are not themselves ABI-compatible.
- Limits of Zig Conveniences. Describe why C-ABI-compatible code may need less-convenient representations instead of Zig errors and slices.
- C strings versus Zig slices. Explain why C strings differ from the Zig u8 slices used earlier: slices store a length, while C strings are pointers to bytes ending in a zero called a NUL terminator.
- Sentinel-terminated Zig string representation. Describe the section’s Zig notation for a zero-terminated string, [:0]u8 or [:0]const u8, and explain why a sentinel-terminated slice remains convenient to work with.
- Enum cases and switches. Explain how enums represent distinct options and how exhaustive switches help handle them as code evolves.
- Enum integer representation. Describe Zig's default integer representation for enums and the stated relevance to C compatibility.
- Enums as table IDs. Trace how an enum provides a type-safe entity ID when adding and accessing data in a table.
- Struct of arrays pattern. Distinguish a struct of arrays from an array of structs and describe the benefits claimed for index-based storage.
- C compatible object design. Explain how the recipe book is presented as an object through a C-compatible API.
- Book and library lifetimes. Describe the resource-management responsibilities of create, close, and quit.
- Nullable creation result. Explain what the optional pointer returned by create means and how a caller should handle it.
- Separate recipe and ingredient storage. Explain why the recipe book stores recipe data and ingredients separately, and how an ingredient identifies its recipe.
- Stable IDs through a hash map. Explain why a list index is unsuitable as a RecipeId when recipes can be deleted, and describe the chosen RecipeId-to-Recipe map, including what Auto and Unmanaged mean.
- Book lifetime for strings. Explain why recipe and ingredient strings are allocated in an arena and how their lifetime relates to the recipe book.
- Recipe identifiers and storage. Describe how the recipe book assigns IDs when creating recipes and uses them to store and retrieve recipes.
- Recipe string lifetime responsibility. Explain who manages strings passed to createRecipe and when duplicating them is useful.
- Ingredient iterator abstraction. Explain why the recipe book uses an iterator for one recipe’s ingredients and describe its next-method convention.
- Iteration and deletion hazards. Explain why modifying the ingredient list while traversing it needs care, especially when deleting a recipe.
- Simplified JSON save format. Explain why the recipe book is converted to a simpler representation before saving, and describe how Zig serializes it to JSON.
- JSON recipe book loading. Trace the loading approach described here, including tokenizing JSON, parsing it with an arena, and duplicating strings.
- Flat data design payoff. Justify why the recipe book’s flat, minimal data design makes serialization easier than an object-oriented arrangement with mutable ingredient lists.
- C-compatible error handling. Explain why error handling needs consideration in C-compatible wrappers and how recipe_book_create uses a nullable pointer to signal failure.
- Error reporting and observability. Explain why error codes improve observability compared with nullable pointers, and why observability is useful.
- Zig error code translation. Describe how the RecipeBook interface represents its failures and translates them into C-friendly error codes.
- Out parameters for results. Explain how an out parameter lets a function return data while using its return value for an error code.
- Whole Recipe Retrieval Design. Explain why the interface returns a whole recipe rather than exposing each field through a separate function.
- C-Compatible Recipe Data. Describe how recipe strings and ingredient sequences are represented for retrieval across the ABI.
- Retrieved Ingredient Buffer Allocation. Explain why retrieving ingredients needs a caller-provided buffer and how FixedBufferAllocator and would_overflow fit into that choice.
- File Access and Serialization. Explain how saving and loading use file access alongside the existing serialization and deserialization work.
- Save and Load Errors. Describe the error cases identified for saving and how errors are represented when loading a recipe book.
- Dynamic library for FFI. Explain why the recipe-book library must be built with the -dynamic flag for Tony’s PHP FFI binding.
What it builds on
- Structs (chapter 2) · The reader has encountered Zig structs.
- Single-Item Pointers (chapter 2) · The reader has encountered pointers in Zig.
- Slicing and dicing (chapter 2) · The earlier use of Zig slices.
- Structs are also namespaces (chapter 2) · Structs as namespaces.
- Methods, sort of (chapter 2) · Struct method syntax.
- Allocating with Allocators (chapter 3) · Allocators and the need to choose an allocator implementation.
- I’ve been Stringing You Along (chapter 2) · Earlier treatment of strings.
Section by section
Introduction
The chapter introduction frames a recipe-book library as a small, reliable solution to a time-pressed programming assignment.
- Compromise in library design: Explain why programmers make compromises and how that pressure shapes the recipe-book assignment: deliver a small, reliable library for Tony’s frontend without doing unnecessary work.
Why it matters: The assignment’s constraints explain why the library should be useful and reliable without becoming more work than necessary.
Key terms: compromise, recipe book library, state management
5.1 What makes a recipe book?
The section turns Tony’s needs into a practical recipe-book library specification, including an interoperability choice, recipe data, and required operations.
- Audience driven library design: Explain how Tony’s application, skills, and time constraints shape the decision to provide a Zig library that his PHP application can use.
Why it matters: The intended user determines what the library needs to provide and how Tony can use it. - Recipe data requirements: Describe the information a recipe must contain in the proposed library.
Why it matters: The library cannot expose useful recipe data until the team agrees on what a recipe contains. - Recipe book API surface: State the operations the agreed library surface needs to provide.
Why it matters: These agreed operations turn Tony’s request into a concrete target for the library. - Pragmatic project scope: Justify the simplified recipe fields and the emphasis on finishing a working library rather than building an elaborate system.
Why it matters: The modest requirements explain why a simple, working design is appropriate here.
Key terms: audience, PHP, foreign function interface (FFI), dynamic library, C ABI, recipe, title, author, ingredients, quantity
5.2 Learning the lingua franca
This section explains why a Zig library meant to communicate with PHP must make its functions compatible with the C ABI.
- C ABI as common tongue: Explain that the Zig library’s functions need to be compatible with the C ABI so they can communicate with Tony’s PHP, because many languages use the C ABI as a common interface.
Why it matters: It explains why C compatibility matters before the book shows how to implement it.
Key terms: C ABI, API surface
5.2.1 So, what is the C ABI, and why do we care about it?
The section explains how linking and ABI rules let compiled programs and libraries work together, and why the C ABI serves as a common interface.
- ABI rules for compatibility: Explain that an ABI is a set of rules for interaction between compiled binaries, including conventions for function calls, data layout, and the stack. Describe why shared rules let code from different languages and compilers work together.
Why it matters: This explains how separately compiled pieces of a larger system can communicate. - Library linking choices: Describe what a system library and linker do, then distinguish static linking from dynamic linking and relate dynamic libraries to the FFI use described here.
Why it matters: The distinction clarifies what it means for a program to use an external library. - System-specific C ABI: Explain why there is no single C ABI for every computer and why C provides a useful common denominator for binary compatibility.
Why it matters: It explains both the reach and the system-specific limits of C-based interoperability.
Key terms: ABI, Application Binary Interface, binary, system library, linker, static linking, dynamic linking, shared linking, FFI, C ABI
5.2.2 What using the C ABI looks like
The section shows how Zig declares C-ABI-compatible interfaces and where its usual type conveniences need adjustment.
- C-Compatible Structs and Exports: Explain how `extern struct` gives a Zig struct a C-compatible layout and how `export` makes C-compatible declarations available when building a library.
Why it matters: These declarations let a Zig library present data and functions through a C-compatible interface. - C Integer Type Matching: Justify using types such as `c_int`, `c_uint`, and `c_long` in C-ABI-compatible functions and data structures.
Why it matters: Matching C's environment-dependent types avoids assuming an integer width at the interface. - Pointers Across the ABI: Explain how pointers allow a C-ABI-compatible interface to refer to data structures that are not themselves ABI-compatible.
Why it matters: Pointer-based interfaces can use internal Zig data without requiring that data's structure to cross the ABI directly. - Limits of Zig Conveniences: Describe why C-ABI-compatible code may need less-convenient representations instead of Zig errors and slices.
Why it matters: It explains why a C-facing API may look less idiomatic than ordinary Zig code.
Key terms: extern struct, export, C ABI, memory layout, c_int, c_uint, c_long, pointers, ABI-compatible data structures, errors
5.2.3 Strings without slices
This subsection contrasts C’s NUL-terminated strings with Zig slices and shows how Zig represents those strings with sentinel-terminated slices.
- C strings versus Zig slices: Explain why C strings differ from the Zig u8 slices used earlier: slices store a length, while C strings are pointers to bytes ending in a zero called a NUL terminator.
Why it matters: This distinction tells you how to recognize the end of a string passed through a C interface. - Sentinel-terminated Zig string representation: Describe the section’s Zig notation for a zero-terminated string, [:0]u8 or [:0]const u8, and explain why a sentinel-terminated slice remains convenient to work with.
Why it matters: It connects C’s string convention to a Zig type you can handle with familiar slice operations.
Key terms: C ABI, C strings, u8 slices, NUL terminator, sentinel value, [:0]u8, [:0]const u8, slice functions
5.2.4 Enums, a semantic superpower
This section explains Zig enums, their integer representation and use as type-safe table indices, and the related struct-of-arrays pattern.
- Enum cases and switches: Explain how enums represent distinct options and how exhaustive switches help handle them as code evolves.
Why it matters: Exhaustive handling helps keep code consistent when its set of options changes. - Enum integer representation: Describe Zig's default integer representation for enums and the stated relevance to C compatibility.
Why it matters: The integer representation makes enums useful both as IDs and at the C interface. - Enums as table IDs: Trace how an enum provides a type-safe entity ID when adding and accessing data in a table.
Why it matters: A typed ID lets the library refer to table entries while retaining the efficiency of an index. - Struct of arrays pattern: Distinguish a struct of arrays from an array of structs and describe the benefits claimed for index-based storage.
Why it matters: The layout gives context for why a table of indexed IDs can be useful for managing many items. - Enum namespaces and methods: State that Zig enum types are namespaces and support method syntax like structs.
Why it matters: This lets enum-related behavior live alongside the enum type.
Key terms: enum, switch, enum cases, else clause, enum variants, unsigned integer, C ABI, type-safe index, Entity, @fromBackingInt
5.3 Library construction
Introduces the upcoming work of turning the desired API behavior into exposed functions and data structures with the intended audience in mind.
5.3.1 Objectively good design
This section designs a C-compatible recipe book object and explains its resource, error-handling, allocator, and I/O choices.
- C compatible object design: Explain how the recipe book is presented as an object through a C-compatible API.
Why it matters: This design makes an object-like library usable through the C ABI. - Book and library lifetimes: Describe the resource-management responsibilities of create, close, and quit.
Why it matters: Matching both object and library cleanup to their lifetimes helps prevent resource leaks. - Nullable creation result: Explain what the optional pointer returned by create means and how a caller should handle it.
Why it matters: Checking the creation result lets a caller recognize allocation failure through the C-compatible interface. - Allocator and I/O choices: Explain why the library chooses SafeAllocator and Io.Threaded and what those choices provide.
Why it matters: These choices align the library’s resource and I/O behavior with its reliability and portability needs.
Key terms: C ABI, RecipeBook, pointer, create, close, quit, deinitialization, optional pointer, null, SafeAllocator
5.3.2 Tabling it
The section designs a recipe book representation that keeps recipe IDs stable and simplifies memory management by storing recipes, ingredients, and strings according to their different needs.
- Separate recipe and ingredient storage: Explain why the recipe book stores recipe data and ingredients separately, and how an ingredient identifies its recipe.
Why it matters: Keeping the two kinds of data separate makes the recipe book easier to manage as recipes change. - Stable IDs through a hash map: Explain why a list index is unsuitable as a RecipeId when recipes can be deleted, and describe the chosen RecipeId-to-Recipe map, including what Auto and Unmanaged mean.
Why it matters: A recipe ID must continue to refer to the intended recipe as other recipes are created or deleted. - Book lifetime for strings: Explain why recipe and ingredient strings are allocated in an arena and how their lifetime relates to the recipe book.
Why it matters: Matching string lifetimes to the book reduces allocation bookkeeping. - Deletion flag alternative: Describe the alternative of marking entries deleted, including its benefit and trade-off.
Why it matters: It shows that stable references can come with different access and ordering trade-offs.
Key terms: RecipeId, ArrayList, ingredients, Recipe, AutoHashMapUnmanaged, HashMap, Unmanaged, Auto, arena allocator, strings
5.3.3 Making it useful
This section builds the recipe book’s Zig-side behavior while explaining its choices about identifiers, string lifetimes, ingredient access, deletion, and API design.
- Recipe identifiers and storage: Describe how the recipe book assigns IDs when creating recipes and uses them to store and retrieve recipes.
Why it matters: The ID connects recipe creation with later access to that recipe. - Recipe string lifetime responsibility: Explain who manages strings passed to createRecipe and when duplicating them is useful.
Why it matters: Keeping borrowed strings alive prevents recipes from retaining pointers to invalid memory. - Ingredient iterator abstraction: Explain why the recipe book uses an iterator for one recipe’s ingredients and describe its next-method convention.
Why it matters: Callers can traverse a recipe’s ingredients without being tied to how all ingredients are stored. - Iteration and deletion hazards: Explain why modifying the ingredient list while traversing it needs care, especially when deleting a recipe.
Why it matters: A deletion loop that skips ingredients could leave part of a removed recipe behind. - Realistic deletion performance: Justify evaluating the deletion loop against expected ingredient counts rather than its Big O notation alone.
Why it matters: It keeps performance work focused on costs that matter at the application’s actual scale. - Audience led API design: Describe the section’s approach to designing a usable recipe-book interface, including the separation between Zig behavior and the later cross-language surface.
Why it matters: An API is easier to use when its shape follows its data and the needs of its callers.
Key terms: RecipeId, RecipeBook, recipe hash map, createRecipe, string arena, dupeCString, outlive, dangling pointer, iterator, next
5.3.4 Recipes should live on for a long time
The section shows how to save and load a recipe book as JSON, and why its flat data design makes that straightforward.
- Simplified JSON save format: Explain why the recipe book is converted to a simpler representation before saving, and describe how Zig serializes it to JSON.
Why it matters: A simple save representation lets the standard library handle the JSON translation. - JSON recipe book loading: Trace the loading approach described here, including tokenizing JSON, parsing it with an arena, and duplicating strings.
Why it matters: The loading path turns saved JSON back into usable recipe book data while accounting for parsing and string ownership. - Flat data design payoff: Justify why the recipe book’s flat, minimal data design makes serialization easier than an object-oriented arrangement with mutable ingredient lists.
Why it matters: The serialization example shows a practical benefit of designing data for simple operations over the whole dataset.
Key terms: std.json, std.json.Stringify, string arena, hash map, std.json.Reader, std.Io.Reader, std.json.parseFromTokenSourceLeaky, arena, dupe, data-oriented design
5.4 The easy part: C compatibility
This section introduces error handling as a key concern when wrapping the Zig recipe book with a C-compatible interface.
- C-compatible error handling: Explain why error handling needs consideration in C-compatible wrappers and how recipe_book_create uses a nullable pointer to signal failure.
Why it matters: A C-compatible interface needs a way to communicate failures across the language boundary.
Key terms: C ABI, error handling, nullable pointers, recipe_book_create
5.4.1 Screaming louder when things go wrong
This section improves C-facing error reporting by translating Zig errors into specific error codes and returning successful data through out parameters.
- Error reporting and observability: Explain why error codes improve observability compared with nullable pointers, and why observability is useful.
Why it matters: Informative failures make a library easier to diagnose and improve. - Zig error code translation: Describe how the RecipeBook interface represents its failures and translates them into C-friendly error codes.
Why it matters: Specific C-friendly codes let library callers distinguish different failures. - Out parameters for results: Explain how an out parameter lets a function return data while using its return value for an error code.
Why it matters: An out parameter separates the function's result data from its success or failure status.
Key terms: observability, nullable pointers, error codes, error set, error values, RecipeBook, out parameter, .ok
5.4.2 Sending over all that data
This section explains how to expose whole recipes and recipe iteration across a C-compatible ABI, using caller-provided buffer memory for retrieved ingredients.
- Whole Recipe Retrieval Design: Explain why the interface returns a whole recipe rather than exposing each field through a separate function.
Why it matters: The interface design makes recipe retrieval convenient without adding many tiny access functions. - C-Compatible Recipe Data: Describe how recipe strings and ingredient sequences are represented for retrieval across the ABI.
Why it matters: These representations let the app receive recipe data in C-compatible forms. - Retrieved Ingredient Buffer Allocation: Explain why retrieving ingredients needs a caller-provided buffer and how FixedBufferAllocator and would_overflow fit into that choice.
Why it matters: This separates the temporary memory needed for retrieved ingredients from the recipe book’s existing strings. - Cross-ABI Recipe Iteration: Describe the section’s approach to letting Tony’s app iterate through all recipes.
Why it matters: Iteration gives the app a way to discover all the recipes.
Key terms: ABI barrier, recipe, granular interface, nul-terminated bytes, pointer, length, RecipeBook, RetrievedIngredient, IngredientIterator, std.heap.FixedBufferAllocator
5.4.3 Saving and loading
This section adds file access and error handling for saving and loading recipe books.
- File Access and Serialization: Explain how saving and loading use file access alongside the existing serialization and deserialization work.
Why it matters: This separates accessing a file from converting the recipe book to and from its stored form. - Save and Load Errors: Describe the error cases identified for saving and how errors are represented when loading a recipe book.
Why it matters: Callers need a way to recognize failures when saving or loading a recipe book.
Key terms: serialization, deserialization, readers, writers, std.Io, error.WriteFailed, file_error, write_failed, Success, translateErr
5.5 What do you think, Tony?
The section shows the recipe-book library being used by Tony’s PHP app and explains why it must be built dynamically for FFI.
- Dynamic library for FFI: Explain why the recipe-book library must be built with the -dynamic flag for Tony’s PHP FFI binding.
Why it matters: The build needs to produce the kind of library Tony’s PHP binding can use.
Key terms: -dynamic, static, dynamic library, FFI bindings
5.6 Next steps
The section briefly recaps the chapter’s library and suggests optional ways to extend or use it.
5.7 Summary
Where this is used later
- Don’t we care about error handling? (chapter 7) · The C ABI and why compatibility with it matters
- Devices for the desktop (chapter 6) · Earlier work with Zig's C compatibility provides context for using a C library.
Concepts explained in this chapter
- data-oriented programmingData-oriented design organizes software around data representation, layout, access patterns, and transformations.
- iteratorThe iterator pattern provides an abstraction for accessing elements sequentially without exposing their underlying representation.
- C ABI compatibilityThe C ABI is the platform-specific binary interface convention commonly designed around the C language's stable data representation and expected by a computer system's operating system and CPU.
- ArenaArena allocation obtains storage from an arena and typically releases the storage collectively rather than freeing individual allocations.
- application binary interfaceAn application binary interface specifies how compiled components interact at the binary level, including calling conventions and data representation.
- lifetimeA lifetime is the period during which a program's data remains valid and available in storage.
- explicit memory managementManual memory management is the explicit allocation, ownership, and release of dynamically used memory by program code.
- memory allocatorAn allocator is an abstraction that obtains and releases memory on behalf of program code.
- foreign function interfaceA foreign function interface is an interface that allows code written in one programming language to call or interoperate with code written in another.
- dynamic linkingDynamic linking is a linking technique in which an executable records its dependency on a separately provided library that is loaded at runtime.
- bufferA buffer is a temporary memory area that holds data before it is processed or transferred.
- error codeAn error code is a value returned or stored to indicate that an operation failed and often identify the failure kind.
- null terminationA NUL terminator is a zero byte placed after text data to mark the end of a byte string.
- error handlingError handling is the representation and handling of failures that can occur during program execution.
- functionA subroutine is a callable sequence of instructions that returns control to its caller when complete.
- dangling pointerA dangling pointer is a pointer that retains an address after the data formerly stored there is no longer valid.
- ownershipMemory ownership is the responsibility for managing the lifetime and eventual release of allocated memory.
- nullNull is a value representing the absence of an object or valid pointed-to item.
- namespaceA namespace is a named scope that groups program declarations and prevents naming conflicts.
- switch statementA switch statement is a control-flow construct that selects code to execute based on an expression's matching case.
- std.Iostd.Io is Zig's standard-library interface for portable input/output operations, including buffered and concurrent I/O.
- sliceA slice is a view representing a portion of a contiguous sequence of elements, typically through a pointer and a length.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
