Blog Name

Announcing Alacritty, a GPU-accelerated terminal emulator

2017-01-05T18:00:00-06:00

Alacritty is a blazing fast, GPU accelerated terminal emulator. It’s written in Rust and uses OpenGL for rendering to be the fastest terminal emulator available. Alacritty is available on GitHub in source form.

Alacritty running vim inside tmux

Alacritty

The rest of this post discusses what Alacritty is, why it was built, who it’s targeted at, and some architectural decisions that have enabled its unparalleled performance. I’ll be giving a technical talk at the January 2017 Rust Meetup in SF if you want to learn more.

About the project

Alacritty is the result of frustration with existing terminal emulators. Using vim inside tmux in many terminals was a particularly bad experience. None of them were ever quite fast enough. Even so, Linux does have some decent alternatives. For example, urxvt and st give good experiences. The major downside with those options is difficulty of configuration and inability to run on non-X11 platforms. The options for macOS are particularly slow–especially with a full-screen terminal on a 4k monitor. None of these terminals are cross-platform–they are usually married to the windowing and font rendering APIs of their native platform.

Alacritty aims to address these issues. The project’s architecture and features are guided by a set of values:

Correctness: Alacritty should be able to properly render modern terminal applications like tmux and vim. Glyphs should be rendered properly, and the proper glyphs should be displayed.
Performance: Alacritty should be the fastest terminal emulator available anywhere.
Appearance: Alacritty should have beautiful font rendering and look fantastic on all supported platforms.
Simplicity: Alacritty should be conservative about which features it offers. As we’ve learned from past terminal emulators, it’s far too easy to become bloated. st taught us that it doesn’t need to be that way. Features like GUI-based configuration, tabs and scrollback are unnecessary. The latter features are better provided by a terminal multiplexer like tmux.
Portability: Alacritty should support major operating systems including Linux, macOS, and Windows.

Initial Features

Many programs work correctly and without issue. vim, tmux, htop, various pagers and many other full-screen applications are rendered properly.

Alacritty is incredibly fast. Compare find /usr or equivalent with your favorite terminal emulator. Keep in mind that command will be faster the second time it’s run due to OS caching. Alacritty’s performance scales well with screen size. Running at larger resolutions will tip the scale further in Alacritty’s favor.

Alacritty’s font rendering is great. Native font rasterization libraries are used on each platform, and sub-pixel anti-aliasing is supported on both macOS and Linux.

macOS and Linux are supported in this pre-alpha release. Windows is not yet part of the list, but the initial offering demonstrates making a cross-platform terminal emulator is possible.

Being a pre-alpha release, there is still pending work in key areas

Less common applications have rendering issues
A small subset of systems have performance issues with the OpenGL renderer
Font rendering on macOS is not as good as the competition
Wayland is not natively supported
Fallback fonts are not supported
Full-screen mode is not supported on Linux

Such issues will be resolved prior to a 1.0 release. Many of them will be resolved far earlier.

What makes Alacritty fast

Alacritty’s biggest claim is that it’s the fastest terminal emulator available. If there’s a case where it’s not, then it’s either a bug in Alacritty or a misconfigured system. Alacritty is fast for two reasons–the OpenGL renderer and the high throughput parser.

OpenGL Rendering

Alacritty’s renderer is capable of doing ~500 FPS with a large screen full of text. This is made possible by efficient OpenGL usage. State changes are minimized as much as possible. Glyphs are rasterized only once and stored in a texture atlas. Instance data for glyphs is uploaded once per frame, and the screen is rendered in only two draw calls.

Alacritty isn’t concerned with trying to only redraw what’s necessary. The entire screen is redrawn each frame because it’s so cheap.

Nominally, Alacritty will draw a new frame whenever the terminal state changes, and only when the state changes. Alacritty will simply sit idle when there’s no new data from the pseudoterminal or input events from the users. This helps significantly with battery life.

Alacritty is very good at processing huge amounts of text. Say that a user wants to cat 1gb_file.txt. There’s a lot of work for the parser to do. If Alacritty were drawing frames constantly on every change, it would take a long time to finish parsing and rendering the contents. Thankfully, V-Sync can help here.

V-Sync limits the frames drawn by Alacritty up to the monitor’s refresh rate. 60Hz is a typical value here. Using this number, there are 16.7ms available per frame. 2ms of that budget is occupied by the renderer, and the remaining 14.7ms are available to the parser to process that huge stream of text. Any text that is added to the terminal and scrolled past between frames will never be drawn. This is a huge performance win! The parser can process many MBs of data between frames, and the user will still see text drawn very smoothly.

The Parser

Alacritty’s performance is enhanced by having a good parser. Rust helped significantly with this by enabling us to write small testable components and combine them without overhead.

Zero-cost abstractions

Rust’s zero-cost abstractions enable building nicely abstracted components and later combining them as if they were hand-written as one initially.

The parser has an advance() method which advances the state and sometimes dispatches actions to the generic Perform argument. Here’s the signature:

pub fn advance<P: Perform>(&mut self, performer: &mut P, byte: u8);

Whenever a byte arrives from the pseudoterminal, it is passed to this advance method. Some bytes will cause state to accumulate in the parser; other bytes will trigger an action. Actions might be something like printing a character to the screen or executing an escape sequence. These actions are defined on a Perform trait which is passed to advance(). For example, here’s the first couple of methods on the trait:

/// Performs actions requested by the Parser
pub trait Perform {
    /// Draw a character to the screen
    fn print(&mut self, char);

    /// Execute a C0 or C1 control function
    fn execute(&mut self, byte: u8);

    // ..
}

To see how this turns into a zero-cost abstraction, let’s look at where the Perform methods are actually called:

match action {
    Action::Print => performer.print(byte as char),
    Action::Execute => performer.execute(byte),
    // ..
}

Assuming the concrete Perform type requests #[inline] on these methods, they will likely be inlined at the call site here and avoid function call overhead.

This same pattern is used for multiple layers of abstraction. Alacritty’s vte::Perform impl actually delegates to an ansi::Handler type for actions which requires additional parsing (eg. csi_dispatch()). The result is that we get nice abstractions for things like vte::Perform and ansi::Handler, and the parsing code compiles into what looks like a big hand-written state machine.

Table-driven parsing

Both the utf8parse and vte crates that were written for Alacritty use table-driven parsers. The cool thing about these is that they have very little branching; utf8parse only has one branch in the entire library!

The transition tables for both vte and utf8parse are written using a procedural macro. The macro translates a high-level definition of the state machine transitions to low-level lookup tables. That is, the state machine can be described like this:

// Transition tables description. Much was omitted for brevity.
pub static STATE_CHANGE: [[u8; 256]; 16] = vt_state_table! {
    State::Anywhere => {
        0x80...0x8f => (Action::Execute, State::Ground),
        0x9b        => State::CsiEntry,
    },
    State::Ground => {
        0x00...0x17 => Action::Execute,
        0x20...0x7f => Action::Print,
        0xf0...0xf4 => (State::Utf8, Action::BeginUtf8),
    },
    State::Escape => {
        0x00...0x17 => Action::Execute,
        0x30...0x4f => (Action::EscDispatch, State::Ground),
        0x58        => State::SosPmApcString,
    },
}

The output of the procedural macro is the transition tables:

// Transition tables
pub static STATE_CHANGE: [[u8; 256]; 16] = [
    [
        0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8,
        0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8,
        0u8, 0u8, 0u8, 0u8, 92u8, 0u8, 92u8, 10u8, 0u8, 0u8,
        // ..
    ],
    // ..
];

Whenever a byte arrives, the parser looks up the table for the current state and indexes with that byte. The value returned contains the next state and any action required to make that transition. This process doesn’t requires branching–it’s a simple, fast lookup.

New libraries

Developing Alacritty required several pieces of library infrastructure which were not available. A non-GPL licensed cross-platform clipboard library, a vte parser, cross-platform font rasterization and fontconfig bindings were all needed to build this project. vte and utf8parse have been published on crates.io. The remaining libraries are still in Alacritty’s source tree and will be published independently at some point.

Here’s a quick run-down of the new libraries:

copypasta: Cross-platform clipboard access library
font: Cross-platform font rasterization library
utf8parse: A table-driven UTF-8 parser
vte: A table-driven terminal protocol parser
ffi-util: Utilities for simplifying wrapping FFI types. This project is from @sfackler’s rust-openssl that I’ve put into a module for wrapping fontconfig C types.

Conclusion

Alacritty is a very fast and usable terminal emulator. Although this is a pre-alpha release, it works well enough for many developers to be used as a daily driver. I’ve personally been using it as my primary terminal for a few months now.

For those wanting to learn more about the project, I’ll be giving a talk about Alacritty at the upcoming Rust Meetup in SF on January 19, 2017. I’m also planning some more technical blog posts about various subsystems of Alacritty.

This post has been discussed in several threads on Reddit and on Hacker News:

Follow me on Twitter if you’d like to be notified about subsequent Alacritty releases and blog posts.

Alacritty’s source is available on GitHub. Try it out for yourself!

From &str to Cow

2016-04-15T19:00:00-05:00

Some of the first Rust code I wrote was a struct with a &str field. As you might imagine, the borrow checker didn’t let me do a lot of things, and the API ergonomics were limited. This article aims to demonstrate the issues with having raw &str references in structs, introduce some intermediate APIs that alleviate the ergonomics but aren’t necessarily efficient, and end with an implementation that is both ergonomic and efficient.

Let’s say we’re making a library for the example.com API. Each API call must be authenticated with a token. A token definition might look like this:

/// Token for example.io API
pub struct Token<'a> {
    raw: &'a str,
}

And maybe there’s an impl for creating a token given a &str.

impl<'a> Token<'a> {
    pub fn new(raw: &'a str) -> Token<'a> {
        Token { raw: raw }
    }
}

This Token impl works really well for &'static str. However, what if a user doesn’t want to embed their authentication secret in the binary? Maybe the secret is loaded from a vault at run time. We might want to write some code like this.

/// Imagine that this function exists
let secret: String = secret_from_vault("api.example.io");
let token = Token::new(&secret[..]);

This implementation has a big limitation; token cannot outlive secret, and that means token can’t escape this stack frame. What if Token just held a String? That would get rid of the lifetime parameter making Token a purely owned type.

Token and its new function look like this after making the change.

struct Token {
    raw: String,
}

impl Token {
    pub fn new(raw: String) -> Token {
        Token { raw: raw }
    }
}

The use case where a String is provided has been fixed.

// this works now
let token = Token::new(secret_from_vault("api.example.io"))

However, this has actively harmed the usability of providing a &'str. For example, this won’t compile:

// doesn't compile
let token = Token::new("abc123");

The consumer of this API would need to manually convert that into a String first.

let token = Token::new(String::from("abc123"));

If new took a &str instead of a String, it could hide String::from in the implementation. However, passing in a String would become less ergonomic, and it would involve and additional heap allocation. Let’s see what that looks like:

// new function now looks like so
impl Token {
    pub fn new(raw: &str) -> Token {
        Token(String::from(raw))
    }
}

// &str can be passed seamlessly
let token = Token::new("abc123");

// Can still use a String, but it needs to be sliced, and
// the new fn will copy it
let secret = secret_from_vault("api.example.io");
let token = Token::new(&secret[..]); // inefficent!

There is a way that new can accept both forms with no allocation needed in the case of a String.

Introducing Into

The standard libary has a trait Into which will help our new problem. The trait definition looks like this:

pub trait Into<T> {
    fn into(self) -> T;
}

The into function it defines is pretty straight-forward; it consumes self (the thing implementing Into) and returns a T (note the type parameter on the trait definition). Here’s how it’s used:

impl Token {
    /// Create a new token
    ///
    /// Can be passed either a &str or String
    pub fn new<S>(raw: S) -> Token
        where S: Into<String>
    {
        Token { raw: raw.into() }
    }
}

// &str
let token = Token::new("abc123");

// String
let token = Token::new(secret_from_vault("api.example.io"));

There’s a lot going on here. First, the function now has a generic type parameter, S. The argument raw has this type. The line reading where S: Into<String> limits the types of S to anything that implements Into<String>. Since the standard library already provides Into<String> for &str and for String, our use case is handled. ¹

Although the ergonomics have been greatly improved, there’s still an issue with this API. Passing a &str to new requires an allocation to store the value as a String.

Cow to the rescue

The standard library has a type std::borrow:Cow which enables us to keep the ergonomics of the Into<String> API while also allowing for borrowed values like a &str.

Here’s the scary-looking definition of Cow:

pub enum Cow<'a, B> where B: 'a + ToOwned + ?Sized {
    Borrowed(&'a B),
    Owned(B::Owned),
}

Let’s break that down.

Cow<'a, B> has two generic parameters; a lifetime 'a, and some type B
B is constrained to 'a + ToOwned + ?Sized
- 'a - B cannot contain a lifetime shorter than 'a
- + ToOwned - B must implement ToOwned.
- + ?Sized - The size of B can be unknown at compile time. This isn’t relevant for our use case, but it means that trait objects may be used with the Cow type.
There’s two variants
- Borrowed(&'a B) - a reference to some object of type B. The lifetime of this reference is the same as the lifetime bound.
- Owned(B::Owned) - The ToOwned trait has an associated type Owned. This variant holds that type.

We want to have a Cow<'a, str>, which will look something like this after type substitution.

enum Cow<'a, str> {
    Borrowed(&'a str),
    Owned(String),
}

In short, Cow<'a, str> will be either a &str with the lifetime 'a, or it will be a String which is not bound by that lifetime. This sounds great for the Token type! It will be able to hold either a &str or a String.

struct Token<'a> {
    raw: Cow<'a, str>
}

impl<'a> Token<'a> {
    pub fn new(raw: Cow<'a, str>) -> Token<'a> {
        Token { raw: raw }
    }
}

// Create the tokens.
let token = Token::new(Cow::Borrowed("abc123"));
let secret: String = secret_from_vault("api.example.io");
let token = Token::new(Cow::Owned(secret));

A Token can now be created with either an owned or a borrowed type, but we’ve lost the API ergonomics! Into can do the same thing for our Cow<'a, str> as it did for a simple String earlier. The final Token implementation looks like this:

struct Token<'a> {
    raw: Cow<'a, str>
}

impl<'a> Token<'a> {
    pub fn new<S>(raw: S) -> Token<'a>
        where S: Into<Cow<'a, str>>
    {
        Token { raw: raw.into() }
    }
}

// Create the tokens.
let token = Token::new("abc123");
let token = Token::new(secret_from_vault("api.example.io"));

Now, a token can be created ergonomically from either a &str or a String. The lifetime bound on Token is no longer a problem for escaping stack frames when created with a String or &'static str; it can even be sent across threads!

let raw = String::from("abc");
let token_owned = Token::new(raw);
let token_static = Token::new("123");

thread::spawn(move || {
    println!("token_owned: {:?}", token_owned);
    println!("token_static: {:?}", token_static);
}).join().unwrap();

Trying to send a token with a non-'static ref will fail.

// Make a ref with non-'static lifetime
let raw = String::from("abc");
let s = &raw[..];
let token = Token::new(s);

// This won't work
thread::spawn(move || {
    println!("token: {:?}", token);
}).join().unwrap();

Indeed, the above example fails with

error: `raw` does not live long enough

If you’re hungry for more examples, please check out the PagerDuty API client which uses Cow extensively.

Thanks for reading!

Notes

1

If you were to go looking for the Into<String> impl for &str and String, you wouldn’t find it. This is because there’s a generic implementation of Into for types implementing From. It’s often said that From implies Into, and it’s because of this blanket impl. The whole thing looks like this

impl<T, U> Into<U> for T where U: From<T> {
    fn into(self) -> U {
        U::from(self)
    }
}

YouCompleteMe, Rust

2016-01-07T18:00:00-06:00

YouCompleteMe now supports Rust auto-completion and GoTo. Rust semantic analysis is provided by racerd, a JSON/HTTP server powered by racer. YCM with Rust provides a superior experience to current vim-racer, emacs-racer, and other racer-based plugins.

YouCompleteMe

For the uninitiated, YouCompleteMe is a fast, fuzzy, as-you-type code-completion engine built originally for Vim. YCM runs on Mac, Linux, and Windows and includes completion engines for C/C++, ObjC, Python, C#, Go, TypeScript, JavaScript, and now Rust. YCM additionally provides an identifier based completion engine to supplement semantic completers and provide completions for languages without native support.

The YCM core, ycmd, exists as an independent project; clients for Vim, Emacs, and Atom all share the same infrastructure. The complete list of known clients is found in the ycmd README. If a ycmd client does not exist for $EDITOR, integrating with ycmd is as simple as integrating with a REST API. The ycmd example client shows how it’s done.

Rust

Rust is a systems programming language that runs blazingly fast, prevents segfaults, and guarantees thread safety.

Support for Rust is now available in YCM. The result is a powerful development environment providing completions and GoTo in your favorite editor. Examples below assume your editor is Vim. For other editors, please reference their YCM client.

Completions

Semantic completions in YCM are provided when a semantic trigger, ., or ::, is detected. In the provided example, you can see a completion menu immediately appear after typing std::, std::collections::, and Vec::; no hotkey was necessary. As you continue to type, YCM fuzzy-filters available completions using your input to narrow the completion list.

GoTo

The YCM Rust Completer provides the GoTo subcommand. GoTo attempts to find where the identifier under the cursor is defined. If successful, a buffer is opened for the file containing the definition, and the cursor is placed on the definition.

The complete GoTo command in Vim is :YcmCompleter GoTo, and I highly recommend mapping it to some hotkey. Example:

nnoremap <Leader>] :YcmCompleter GoTo<CR>

YCM Configuration (Vim)

Rust completions and GoTo from the current crate and its dependencies will be available without any additional configuration. For completions in the standard library, a single variable g:ycm_rust_src_path must be defined in your .vimrc.

" Naturally, this needs to be set to wherever your rust
" source tree resides.
let g:ycm_rust_src_path = '/usr/local/rust/rustc-1.5.0/src'

Differences from vim-racer, emacs-racer, and others

Since racerd, and subsequently YCM’s Rust Completer are powered by racer, the same code-completion and find-definition features are available. The addition of YCM to this equation provides a massive quality-of-life improvement over the existing plugins:

No hotkey required for completions
Fuzzy search of available completions
Identifier-based completion engine to supplement rust completions
Performance: Completions are cached within YCM, and latency with racerd is typically only a few ms once files are cached from disk. This is discussed more in the racerd section following.

racerd

racerd is suitable for providing completions and find-definition support for any Rust IDE and is not constrained to YCM. It provides several benefits over integrating racer via the command line or with the racer daemon flag.

Persistent file caching: When starting a new racer process for every completion, or when running racer in daemon mode, the cache is thrown out after each operation. Racerd keeps this cache between requests. This gives a nice performance boost since files only need to be read from disk once.
Support for dirty buffers: Racerd’s JSON API supports a buffers field - a list of file paths (which need not exist) and associated contents which is added to the racer cache before performing a query. This feature eliminates the need for temporary files.
HTTP/JSON API: Very effective method for integrating a semantic completion engine. Just about every language has a built-in or library for querying such an API, and it is extremely performant on localhost (a few ms for completing out of standard library). The process is long lived; there is no process startup overhead for each query. Racerd also has extensive API documentation.

Giving Thanks

YouCompleteMe would not be the fantastic project it is, both technically and as a positive open-source community, without the work of @Valloric and the YCM team @micbou, @oblitum, @vheon, and @puremourning. racerd and YCM’s Rust completer would not have been possible without @phildawes’ fantastic racer library. Thanks to @birkenfeld for his assistance implementing some changes in racer to make racerd possible. Thanks to @reem whom I pestered with far too many questions in #iron. Finally, thanks to the YCM team for reading drafts of this post.