Este é um exemplo de uma nota do instrutor. Nós as usaremos para adicionar informações complementares aos slides. Elas podem ser tanto pontos-chave que o instrutor deve cobrir quanto respostas a perguntas típicas que surgem em sala de aula.

• No Debian/Ubuntu, você também pode instalar o Cargo, o código-fonte do Rust e o formatador Rust com apt. Entretanto, isto lhe fornece uma versão desatualizada do Rust e pode levar a comportamentos inesperados. O comando seria:

sudo apt install cargo rust-src rustfmt

• Nós sugerimos a utilização do VS Code para editar o código (mas qualquer editor LSP - Language Server Protocol - funciona com o rust-analyzer3).

• Algumas pessoas também gostam de usar a família de IDEs JetBrains, que fazem suas próprias análises, mas têm suas próprias vantagens e desvantagens. Se você preferi-las, pode instalar o Plugin Rust. Observe que, a partir de Janeiro de 2023, a depuração funciona apenas na versão CLion do pacote JetBrains IDEA.

Pontos chave:

• O Rust tem um cronograma de lançamento rápido com um novo lançamento saindo a cada seis semanas. Novos lançamentos mantêm compatibilidade com versões anteriores — além disso, eles habilitam novas funcionalidades.

• Existem três canais de lançamento: “stable”, “beta” e “nightly”.

• Novos recursos estão sendo testados em “nightly”, “beta” é o que se torna “stable” a cada seis semanas.

• Dependências também podem ser resolvidas a partir de registros alternativos, git, pastas, e outros mais.

• O Rust também tem edições: a edição atual é o Rust 2021. As edições anteriores foram o Rust 2015 e o Rust 2018.

  • As edições podem fazer alterações incompatíveis com versões anteriores da linguagem.

  • Para evitar quebra de código, as edições são opcionais: você seleciona a edição para o seu crate através do arquivo Cargo.toml.

  • Para evitar a divisão do ecossistema, os compiladores Rust podem misturar código escrito para diferentes edições.

  • Mencione que é muito raro usar o compilador diretamente, não através do cargo (a maioria dos usuários nunca o faz).

  • Pode valer a pena mencionar que o próprio Cargo é uma ferramenta extremamente poderosa e abrangente. Ele é capaz de muitos recursos avançados, incluindo, entre outros:

    • Estrutura do projeto/pacote
    • Espaços de trabalho
    • Dependências de desenvolvimento e gerenciamento/cache de dependência de tempo de execução
    • Criar scripts
    • Instalação global
    • Também é extensível com plugins de sub-comando (tais como cargo clippy).

  • Leia mais no livro oficial do Cargo

A maioria dos exemplos de código são editáveis, como mostrado acima. Alguns exemplos de código não são editáveis por vários motivos:

• Os playgrounds embutidos não conseguem executar testes unitários. Copie o código e cole no Playground real para demonstrar os testes unitários.

• Os playgrounds embutidos perdem seu estado no momento em que você navega para outra página! Esta é a razão pela qual os alunos devem resolver os exercícios usando uma instalação do Rust local ou via Playground real.

Tente encorajar os participantes do curso a instalar o Cargo e usar um editor local. Isso facilitará a vida deles, pois eles terão um ambiente normal de desenvolvimento.

Lembre aos alunos que:

• Eles devem fazer perguntas na hora, não as guarde para o fim.
• A aula é para ser interativa e as discussões são muito encorajadas!
  • Como instrutor, você deve tentar manter as discussões relevantes, ou seja, mantenha as discussões relacionadas a como o Rust faz as coisas versus alguma outra linguagem. Pode ser difícil encontrar o equilíbrio certo, mas procure permitir mais discussões, uma vez que elas engajam as pessoas muito mais do que uma comunicação unidirecional.
• As perguntas provavelmente farão com que falemos sobre coisas antes dos slides.
  • Isso está perfeitamente OK! A repetição é uma parte importante do aprendizado. Lembre-se que os slides são apenas um suporte e você está livre para ignorá-los quando quiser.

A ideia para o primeiro dia é mostrar apenas o suficiente de Rust para poder falar sobre o famoso borrow checker (verificador de empréstimos). A maneira como o Rust lida com a memória é uma característica importante e devemos mostrar isso aos alunos imediatamente.

Se você estiver ensinando isso em uma sala de aula, este é um bom lugar para repassar o cronograma. Sugerimos dividir o dia em duas partes (seguindo os slides):

• Manhã: 9h às 12h,
• Tarde: 13h às 16h.

É claro que você pode ajustar isso conforme necessário. Certifique-se de incluir pausas, recomendamos uma a cada hora!

Rust se encaixa na mesma área que C++:

• Alta flexibilidade.
• Alto nível de controle.
• Pode ser reduzido para dispositivos com menor poder computacional, tais como microcontroladores.
• Não possui runtime ou coletor de lixo (garbage collection).
• Concentra-se em confiabilidade e segurança sem sacrificar o desempenho.

Este slide tenta deixar os alunos familiarizados com o código em Rust. Eles irão ver bastante conteúdo nos próximos três dias, então começamos devagar com algo familiar.

Pontos chave:

• Rust é muito parecido com outras linguagens na tradição C/C++/Java. É imperativo (não funcional) e não tenta reinventar as coisas, a menos que seja absolutamente necessário.

• Rust é moderno com suporte total para coisas como Unicode.

• Rust usa macros para situações em que você deseja ter um número variável de argumentos (sem sobrecarga de função).

• Macros “higiênicas” significam que elas não capturam acidentalmente identificadores do escopo em que são usadas. As macros em Rust são, na verdade, apenas parcialmente “higiênicas”.

• Rust é multi-paradigma. Por exemplo, ele possui funcionalidades de programação orientada à objetos poderosas, e, embora não seja uma linguagem funcional, inclui uma série de conceitos funcionais.

O código implementa a conjectura de Collatz: acredita-se que o loop sempre termina, mas isso ainda não está provado. Edite o código e tente diferentes entradas.

Pontos chave:

• Explique que todas as variáveis tipadas estaticamente. Tente remover i32 para acionar a inferência de tipo. Em vez disso, tente com i8 e cause um estouro de número inteiro (integer overflow) em tempo de execução.

• Altere let mut x para let x, discuta o erro do compilador.

• Mostre como print! cause um erro de compilação se os argumentos não corresponderem à string de formato.

• Mostre como você precisa usar {} como um espaço reservado se quiser imprimir uma expressão que seja mais complexa do que apenas uma única variável.

• Mostre aos alunos a biblioteca padrão (standard library), mostre como pesquisar std::fmt, o qual possui as regras da mini-linguagem de formatação. É importante que os alunos se familiarizem com pesquisas na biblioteca padrão.

  • Em um shell rustup doc std::fmt abrirá um navegador na documentação std::fmt local.

Certifique-se de perguntar à classe com quais linguagens de programação eles têm experiência. Dependendo da resposta você pode destacar diferentes características do Rust:

• Experiência com C ou C++: Rust elimina toda uma classe de erros em tempo de execução através do verificador de empréstimos (borrow checker). Você obtém desempenho como em C e C++, mas sem os problemas de insegurança de memória. Além disso, você tem uma linguagem com funcionalidades modernas como correspondência de padrões e gerenciamento de dependência integrado.

• Experiência com Java, Go, Python, JavaScript…: Você tem a mesma segurança de memória como nessas linguagens, além de uma semelhança com linguagens de alto nível. Além disso você obtém desempenho rápido e previsível como C e C++ (sem coletor de lixo ou “garbage collector”) bem como acesso a hardware de baixo nível (caso você precise)

É possível produzir vazamentos de memória no Rust (seguro). Alguns exemplos são:

• Você pode usar Box::leak para vazar um ponteiro. Um uso para isso poderia ser para obter variáveis estáticas inicializadas e dimensionadas em tempo de execução
• Você pode usar std::mem::forget para fazer o compilador “esquecer” sobre um valor (o que significa que o destrutor nunca é executado).
• Você também pode criar acidentalmente uma referência cíclica com Rc ou Arc.
• Na verdade, alguns considerarão que preencher infinitamente uma coleção (estruturas de dados) seja um vazamento de memória e o Rust não protege disso.

Para o propósito deste curso, “Sem vazamentos de memória” deve ser entendido como “Praticamente sem vazamentos de memória acidentais”.

Pontos chave:

• O estouro de números inteiros é definido por meio da flag overflow-checks em tempo de compilação. Se habilitada, o programa causará um pânico (uma falha controlada do programa). Caso contrário, será usada a semântica wrap-around. Por padrão, você obtém pânicos em modo de depuração (cargo build) e wrap-around em modo de produção (cargo build --release).

• A verificação de limites (“bounds checking”) não pode ser desativada com uma flag do compilador. Ela também não pode ser desativada diretamente com a palavra-chave unsafe. No entanto, unsafe permite que você chame funções como slice::get_unchecked que não faz verificação de limites.

Pontos chave:

• Abstrações de custo zero, semelhantes ao C++, significa que você não precisa ‘pagar’ por construções de programação de alto nível com memória ou CPU. Por exemplo, escrever um loop usando for deve resultar aproximadamente no mesmo nível de instruções de baixo nível quanto usar a construção .iter().fold().

• Pode valer a pena mencionar que Rust enums são ‘Tipos de Dados Algébricos’ (‘Algebraic Data Types’), também conhecidos como ‘tipos de soma’, que permitem que o sistema de tipos expresse coisas como Option<T> e Result<T, E>.

• Lembre as pessoas de lerem os erros — muitos desenvolvedores se acostumaram ignore as longas mensagens do compilador. O compilador Rust é significativamente mais “verbal” do que outros compiladores. Muitas vezes, ele lhe fornecerá sugestões práticas, prontas para copiar e colar em seu código.

• A biblioteca padrão do Rust (Rust standard library) é pequena comparada a linguagens como Java, Python e Go. Rust não vem com várias coisas que você pode considerar padrão e essencial:

  • um gerador de números aleatórios, mas veja rand.
  • suporte para SSL ou TLS, mas consulte rusttls.
  • suporte para JSON, mas consulte serde_json. O raciocínio por trás disso é que funcionalidade na biblioteca padrão não pode ser descartada, portanto ela tem que ser muito estável. Para os exemplos acima, a comunidade do Rust ainda está trabalhando para encontrar a melhor solução — e talvez não exista uma única “melhor solução” para algumas dessas coisas. Rust vem com um gerenciador de pacotes embutido na forma de Cargo e isso torna trivial baixar e compilar crates de terceiros. Uma consequência disso é que a biblioteca padrão pode ser menor.

  Descobrir bons crates de terceiros pode ser um problema. Sites como https://lib.rs/ ajudam com isso, permitindo que você compare métricas de crates para encontrar um bom e confiável.

• rust-analyzer é uma implementação LSP bem suportada usada pelas principais IDEs e editores de texto.

Há algumas sintaxes que não são mostradas acima:

• Strings brutas permitem que você crie um valor &str com caracteres de escape desabilitados: r"\n" == "\\n". Você pode embutir aspas duplas utilizando uma quantidade igual de # em Ambos os lados das aspas:

  fn main() {
      println!(r#"<a href="link.html">link</a>"#);
      println!("<a href=\"link.html\">link</a>");
  }

• Strings de byte permitem que você crie um valor &[u8] diretamente:

  fn main() {
      println!("{:?}", b"abc");
      println!("{:?}", &[97, 98, 99]);
  }

• Todos os sublinhados em números podem ser omitidos, eles são apenas para legibilidade. Por exemplo, 1_000 pode ser escrito como 1000 (ou 10_00), e 123_i64 pode ser escrito como 123i64.

Pontos chave:

Vetores:

• O valor do tipo matriz [T; N] comporta N elementos (constante em tempo de compilação) do mesmo tipo N. Note que o tamanho de uma matriz é parte do seu tipo, o que significa que [u8; 3] e [u8; 4] são considerados dois tipos diferentes.

• Nós podemos usar literais para atribuir valores para matrizes.

• Na função main, o comando print pede a implementação de depuração (debug) com o parâmetro de formato formato ?: {} produz a saída padrão, {:?} produz a saída de depuração. Nós também poderíamos ter usado {a} e {a:?} sem especificar o valor depois da string de formato.

• Adicionando #, p.ex. {a:#?}, invoca um formato “pretty printing” (“impressão bonita”), que pode ser mais legível.

Tuplas:

• Assim como matrizes, tuplas têm tamanho fixo.

• Tuplas agrupam valores de diferentes tipos em um tipo composto.

• Campos de uma tupla podem ser acessados com um ponto e o índice do valor, e.g. t.0, t.1.

• A tupla vazia () também é conhecida como “tipo unidade” (unit type). É tanto um tipo quanto o único valor válido desse tipo - ou seja, o tipo e seu valor são expressos como (). É usado para indicar, por exemplo, que uma função ou expressão não tem valor de retorno, como veremos em um slide futuro.

  • Você pode pensar nisso como um void, que talvez lhe seja familiar de outras linguagens de programação.

Pontos chave:

• Certifique-se de observar a diferença entre let mut ref_x: &i32 e let ref_x: &mut i32. O primeiro representa uma referência mutável que pode ser ligada a diferentes valores, enquanto o segundo representa uma referência a um valor mutável.

• Nós criamos uma slice emprestando a e especificando os índices de início e fim entre colchetes.

• Se a slice começa no índice 0, a sintaxe de range (faixa) nos permite omitir o índice inicial, o que significa que &a[0..a.len()] e &a[..a.len()] são idênticos.

• O mesmo vale para o último índice, logo &a[2..a.len()] e &a[2..] são idênticos.

• Para criar facilmente uma slice de uma matriz completa, podemos utilizar&a[..].

• s é uma referência a uma slice de i32. Observe que o tipo de s (&[i32]) não menciona mais o tamanho da matriz. Isso nos permite realizar cálculos em slices de tamanhos diferentes.

• As slices sempre pegam emprestado de outro objeto. Neste exemplo, a deve permanecer ‘vivo’ (em escopo) por pelo menos tanto tempo quanto nossa slice.

• A questão sobre a modificação de a[3] pode gerar uma discussão interessante, mas a resposta é que por motivos de segurança de memória você não pode fazer isso por meio de a neste ponto durante a execução, mas você pode ler os dados de a e s com segurança. Isto funciona antes da criação do slice, e novamente depois de println, quando o slice não é mais necessário. Mais detalhes serão explicados na seção do verificador de empréstimos.

• &str introduz uma slice de string, a qual é uma referência imutável para os dados da string em formato UTF-8 armazenados em um bloco de memória. Literais de string ("Hello") são armazenadas no código binário do programa.

• O tipo String do Rust é um invólucro ao redor de uma matriz de bytes. Assim como um Vec<T>, ele é owned.

• Da mesma forma que outros tipos, String::from() cria uma string a partir de um literal; String::new() cria uma nova string vazia, na qual dados de string podem ser adicionados com os métodos push() e push_str().

• A macro format!() é uma maneira conveniente de gerar uma string owned a partir de valores dinâmicos. Ela aceita os mesmos formatadores que println!().

• Você pode emprestar slices &str de String através do operador & e, opcionalmente, selecionar um range (“intervalo”).

• Para programadores C++: pense em &str como const char* de C++, mas que sempre aponta para uma string válida na memória. Em Rust, String é um equivalente aproximado de std::string de C++ (principal diferença: ele só pode conter bytes codificados em UTF-8 e nunca usará uma otimização de string pequena).

• Nos referimos em main a uma função escrita abaixo. Nem declarações prévias e nem cabeçalhos são necessários.
• Os parâmetros de declaração são seguidos por um tipo (o inverso de algumas linguagens de programação) e, em seguida, um tipo de retorno.
• A última expressão em um corpo de uma função (ou qualquer bloco) torna-se o valor de retorno. Simplesmente omita o ; no final da expressão.
• Algumas funções não têm valor de retorno e retornam o ‘tipo unitário’, (). O compilador irá inferir isso se o tipo de retorno -> () for omitido.
• A expressão de intervalo no loop for em imprimir_fizzbuzz_para() contém =n, o que faz com que inclua o limite superior.

• Mostre aos alunos os documentos gerados para o crate rand em docs.rs/rand.

• Este curso não inclui o rustdoc nos slides, apenas para economizar espaço, mas em código real eles devem estar presentes.

• Os comentários internos do documento são discutidos posteriormente (na página sobre módulos) e não precisam ser ser abordados aqui.

• Os comentários do Rustdoc podem conter trechos de código-fonte, que podem ser executados e testados por meio de cargo test. Nós discutiremos estes testes na seção de Testes.

• Add a static method called Rectangle::new and call this from main:

  fn new(width: u32, height: u32) -> Rectangle {
      Rectangle { width, height }
  }

• While technically, Rust does not have custom constructors, static methods are commonly used to initialize structs (but don’t have to). The actual constructor, Rectangle { width, height }, could be called directly. See the Rustnomicon.

• Add a Rectangle::square(width: u32) constructor to illustrate that such static methods can take arbitrary parameters.

• Ao usar tipos genéricos, o Into<T> da biblioteca padrão pode fornecer um tipo de polimorfismo limitado nos tipos de argumento. Veremos mais detalhes em uma seção posterior.

Algumas coisas a considerar ao resolver os exercícios:

• Se possível, use uma instalação local do Rust. Desta forma, você pode obter preenchimento automático em seu editor. Veja a página sobre Utilização do Cargo para detalhes sobre instalação do Rust.

• Alternativamente, utilize o Rust Playground.

Os trechos de código não são editáveis de propósito: os trechos de código embutidos perdem seu estado se você sair da página.

Depois de ver os exercícios, você pode ver as soluções fornecidas.

A solução e a resposta para a seção de bônus estão disponíveis na Seção Soluções.

O uso da referência &matriz em for n in &matriz é uma prévia sutil das questões de propriedade que surgirão à tarde.

Sem o &…

• O loop teria sido o que consome a matriz. Esta é uma mudança introduzida na Edição de 2021.
• Uma cópia implícita da matriz teria ocorrido. Como i32 é um tipo de cópia (copy type), então [i32; 3] também é um tipo de cópia.

Pontos Chave:

• O objetivo deste slide é mostrar que os blocos têm um tipo e um valor em Rust.
• Você pode mostrar como o valor do bloco muda alterando a última linha do bloco. Por exemplo, adicionar/remover um ponto e vírgula (;) ou usar um return.

Como if é uma expressão e deve ter um tipo específico, ambos os blocos de ramificação devem ter o mesmo tipo. Considere mostrar o que acontece se você adicionar um ; depois de x / 2 no segundo exemplo.

• A iteração de índice não é uma sintaxe especial no Rust apenas para esse caso.
• (0..10) é um range (intervalo) que implementa um trait Iterator.
• step_by é um método que retorna outro Iterator que pula outros elementos alternadamente.
• Modifique os elementos no vetor e explique os erros de compilação. Altere o vetor v para ser mutável e o loop for para for x in v.iter_mut().

• Interrompa o loop com um valor (por exemplo, break 8) e imprima-o.
• Observe que loop é a única construção de loop que retorna um valor não trivial . Isso ocorre porque é garantido que ele será executado pelo menos uma vez (diferente de loops while e for).

• Devido à inferência de tipos, o i32 é opcional. Gradualmente mostraremos os tipos cada vez menos à medida que o curso progride.

Este slide demonstra como o compilador Rust infere tipos com base em restrições dadas por declarações e usos de variáveis.

É muito importante enfatizar que variáveis declaradas assim não são de um tipo dinâmico “qualquer tipo” que possa armazenar quaisquer dados. O código de máquina gerado por tal declaração é idêntico à declaração explícita de um tipo. O compilador faz o trabalho para nós e nos ajuda a escrever um código mais conciso.

O código a seguir informa ao compilador para copiar para um determinado contêiner genérico sem que o código especifique explicitamente o tipo contido, usando _ como placeholder:

fn main() {
    let mut v = Vec::new();
    v.push((10, false));
    v.push((20, true));
    println!("v: {v:?}");

    let vv = v.iter().collect::<std::collections::HashSet<_>>();
    println!("vv: {vv:?}");
}

collect depende de FromIterator, que HashSet implementa.

• Mencione que const se comporta semanticamente de maneira similar ao constexpr de C++.
• Por outro lado, static é muito mais similar a um const ou variável global mutável em C++.
• static fornece identidade de objeto: um endereço na memória e estado conforme exigido por tipos com mutabilidade interior tais como Mutex<T>.
• Não é muito comum que alguém precise de uma constante avaliada em tempo de execução, mas é útil e mais seguro do que usar uma variável estática.
• Dados de thread_local podem ser criados com a macro std::thread_local.

Tabela de propriedades:

• Definição: Shadowing é diferente da mutação, porque após a sobreposição (shadowing), os locais de memória de ambas as variáveis existem ao mesmo tempo. Ambas estão disponíveis com o mesmo nome, dependendo de onde você as usa no código.
• Uma variável sobreposta pode ter um tipo diferente.
• A sobreposição parece obscura a princípio, mas é conveniente para manter os valores após .unwrap().
• O código a seguir demonstra por que o compilador não pode simplesmente reutilizar locais de memória ao sobrepor uma variável imutável em um escopo, mesmo que o tipo não seja alterado.

fn main() {
    let a = 1;
    let b = &a;
    let a = a + 1;
    println!("{a} {b}");
}

Pontos Chave:

• Enumerações permitem coletar um conjunto de valores em um tipo
• Esta página oferece um tipo de enum MoedaJogada com duas variantes Cara e Coroa. Você pode observar o namespace ao usar variantes.
• Este pode ser um bom momento para comparar Structs e Enums:
  • Em ambos, você pode ter uma versão simples sem campos (unit struct, ou estrutura unitária) ou uma com diferentes tipos de campo.
  • Em ambos, as funções associadas são definidas dentro de um bloco impl.
  • Você pode até mesmo implementar as diferentes variantes de uma Enum com Structs separadas, mas elas não seriam do mesmo tipo, como seriam se todas fossem definidas em uma Enum.

• Os valores nas variantes de uma enum só podem ser acessados após uma correspondência de padrão. O padrão vincula referências aos campos no “braço” do match após =>.
  • A expressão é comparada com os padrões de cima a baixo. Não existe fall-through como em C ou C++.
  • A expressão match possui um valor. O valor é o da última expressão executada em um “braço” do match.
  • Começando do topo, nós procuramos qual padrão corresponde ao valor, e então executamos o código após a flecha. Quando uma correspondência é encontrada, nós paramos.
• Demonstre o que acontece quando a busca não abrange todas as possibilidades. Mencione a vantagem que o compilador do Rust oferece confirmando quando todos os casos foram tratados.
• match inspeciona um campo discriminant escondido na enum.
• É possível recuperar o discriminante chamando std::mem::discriminant()
  • Isso é útil, por exemplo, ao implementar PartialEq para structs nas quais comparar valores de campos não afeta a igualdade.
• WebEvent::Click { ... } não é exatamente o mesmo que WebEvent::Click(Click) com uma struct Click { ... } top-level. A versão no próprio local (inline) não permite implementar traits, por exemplo.

Pontos Chave:

• Internamente Rust utiliza um campo (discriminante) para saber qual a variante da enum.

• É possível controlar a discriminante se necessário (e.g., para compatibilidade com C):

  #[repr(u32)]
  enum Bar {
      A,  // 0
      B = 10000,
      C,  // 10001
  }
  
  fn main() {
      println!("A: {}", Bar::A as u32);
      println!("B: {}", Bar::B as u32);
      println!("C: {}", Bar::C as u32);
  }

  Sem repr, o tipo da discriminante usa 2 bytes, porque 10001 cabe em 2 bytes.

• Tente outros tipos como

  • dbg_size!(bool): tamanho 1 bytes, alinhamento: 1 bytes,
  • dbg_size!(Option<bool>): tamanho 1 bytes, alinhamento: 1 bytes (otimização de nicho, seja abaixo),
  • dbg_size!(&i32): tamanho 8 bytes, alinhamento: 8 bytes (em uma máquina de 64-bits),
  • dbg_size!(Option<&i32>): tamanho 8 bytes, alinhamento: 8 bytes (otimização de ponteiro nulo, veja abaixo).

• Otimização de nicho: Rust vai mesclar padrões de bits não utilizados na discriminante da enum.

• Otimização de ponteiro nulo: para alguns tipos, o Rust garante que size_of::<T>() se iguala size_of::<Option<T>>().

  Código de exemplo caso queira mostrar como a representação em bits pode ser na prática. É importante apontar que o compilador não oferece nenhuma garantia a respeito dessa representação, portanto isso é completamente inseguro.

  use std::mem::transmute;
  
  macro_rules! dbg_bits {
      ($e:expr, $bit_type:ty) => {
          println!("- {}: {:#x}", stringify!($e), transmute::<_, $bit_type>($e));
      };
  }
  
  fn main() {
      // TOTALLY UNSAFE. Rust provides no guarantees about the bitwise
      // representation of types.
      unsafe {
          println!("Representação em bits de booleano");
          dbg_bits!(false, u8);
          dbg_bits!(true, u8);
  
          println!("Representação em bits de Option<bool>");
          dbg_bits!(None::<bool>, u8);
          dbg_bits!(Some(false), u8);
          dbg_bits!(Some(true), u8);
  
          println!("Representação em bits de Option<Option<bool>>");
          dbg_bits!(Some(Some(false)), u8);
          dbg_bits!(Some(Some(true)), u8);
          dbg_bits!(Some(None::<bool>), u8);
          dbg_bits!(None::<Option<bool>>, u8);
  
          println!("Representação em bits de Option<&i32>");
          dbg_bits!(None::<&i32>, usize);
          dbg_bits!(Some(&0i32), usize);
      }
  }

  Exemplo mais complexo caso queira demonstrar o que acontece ao encadear mais de 256 Options de uma vez.

  #![recursion_limit = "1000"]
  
  use std::mem::transmute;
  
  macro_rules! dbg_bits {
      ($e:expr, $bit_type:ty) => {
          println!("- {}: {:#x}", stringify!($e), transmute::<_, $bit_type>($e));
      };
  }
  
  // Macro to wrap a value in 2^n Some() where n is the number of "@" signs.
  // Increasing the recursion limit is required to evaluate this macro.
  macro_rules! many_options {
      ($value:expr) => { Some($value) };
      ($value:expr, @) => {
          Some(Some($value))
      };
      ($value:expr, @ $($more:tt)+) => {
          many_options!(many_options!($value, $($more)+), $($more)+)
      };
  }
  
  fn main() {
      // TOTALLY UNSAFE. Rust provides no guarantees about the bitwise
      // representation of types.
      unsafe {
          assert_eq!(many_options!(false), Some(false));
          assert_eq!(many_options!(false, @), Some(Some(false)));
          assert_eq!(many_options!(false, @@), Some(Some(Some(Some(false)))));
  
          println!("Representação em bits de uma sequência de 128 Option's.");
          dbg_bits!(many_options!(false, @@@@@@@), u8);
          dbg_bits!(many_options!(true, @@@@@@@), u8);
  
          println!("Representação em bits de uma sequência de 256 Option's.");
          dbg_bits!(many_options!(false, @@@@@@@@), u16);
          dbg_bits!(many_options!(true, @@@@@@@@), u16);
  
          println!("Representação em bits de uma sequência de 257 Option's.");
          dbg_bits!(many_options!(Some(false), @@@@@@@@), u16);
          dbg_bits!(many_options!(Some(true), @@@@@@@@), u16);
          dbg_bits!(many_options!(None::<bool>, @@@@@@@@), u16);
      }
  }

• Ao contrário de match, if let não precisa cobrir todas as ramificações. Isso pode torná-lo mais conciso do que match.

• Um uso comum é lidar com valores Some ao trabalhar com Option.

• Ao contrário de match, if let não suporta cláusulas de guarda para correspondência de padrões.

• Desde 1.65, uma construção let-else semelhante permite fazer uma atribuição de desestruturação, ou se falhar, ter um bloco de ramificação sem retorno (panic/return/break/continue):

  fn main() {
      println!("{:?}", second_word_to_upper("foo bar"));
  }
   
  fn second_word_to_upper(s: &str) -> Option<String> {
      let mut it = s.split(' ');
      let (Some(_), Some(item)) = (it.next(), it.next()) else {
          return None;
      };
      Some(item.to_uppercase())
  }
  

• Ressalte que o loop while let continuará executando enquanto o valor corresponder ao padrão.
• Você pode reescrever o loop while let como um loop infinito com uma instrução if que é interrompido quando não houver mais nenhum valor para desempacotar (unwrap) para iter.next(). O while let fornece um atalho para o cenário acima.

• Salve o resultado de uma expressão de correspondência match em uma variável e imprima-a.
• Remova .as_deref() e explique o erro gerado.
  • std::env::Args().next() retorna um Option<&String>, porém match não funciona com o tipo String.
  • as_deref() transforma um Option<T> em Option<&T::Target>. Em nosso caso, isso transforma um Option<String> em Option<&str>.
  • Agora podemos usar a correspondência de padrões em um &str dentro de Option.

Pontos Chave:

• Você pode apontar como alguns caracteres específicos podem ser usados em um padrão
  • | como um ou
  • .. pode expandir o quanto for necessário
  • 1..=5 representa um intervalo inclusivo
  • _ é um curinga
• Pode ser útil mostrar como funciona a vinculação, por exemplo, substituindo um caractere curinga por uma variável ou removendo as aspas ao redor de q.
• Você pode demonstrar correspondência em uma referência.
• Este pode ser um bom momento para trazer à tona o conceito de padrões irrefutáveis, já que o termo pode aparecer em mensagens de erro.

Pontos chave:

• A expressão if/else está retornando um enum que é posteriormente descompactado com um match.
• Você pode tentar adicionar uma terceira variante à definição de Enum e exibir os erros ao executar o código. Aponte os lugares onde seu código agora é “não exaustivo” e como o compilador tenta lhe dar dicas.

• Modifique os valores em foo para corresponder com os outros padrões.
• Adicione um novo campo a Foo e faça mudanças nos padrões conforme necessário.
• A diferença entre uma captura (capture) e uma expressão constante pode ser difícil de perceber. Tente modificar o 2 no segundo braço para uma variável, e veja que, de forma sútil, não funciona. Mude para const e veja funcionando novamente.

• Desestruturar slices de tamanho desconhecido é possível utilizando padrões de tamanho fixo.

  fn main() {
      inspect(&[0, -2, 3]);
      inspect(&[0, -2, 3, 4]);
  }
  
  #[rustfmt::skip]
  fn inspect(slice: &[i32]) {
      println!("Fale-me sobre {slice:?}");
      match slice {
          &[0, y, z] => println!("Primeiro é 0, y = {y} e z = {z}"),
          &[1, ..]   => println!("Primeiro é 1 e o resto foi ignorado"),
          _          => println!("Todos os elementos foram ignorados"),
      }
  }

• Crie um novo padrão usando _ para representar um elemento.

• Adicione mais valores ao vetor.

• Aponte que .. vai expandir para levar em conta um número diferente de elementos.

• Mostre correspondência com a cauda usando os padrões [.., b] and [a@..,b]

Pontos Chave:

• Guardas de correspondência, como um recurso de sintaxe separado, são importantes e necessárias quando se quer expressar ideias mais complexas do que somente o padrão permitiria.
• Eles não são iguais à expressão if separada dentro do bloco de correspondência. Uma expressão if dentro do bloco de ramificação (depois de =>) acontece depois que a correspondência é selecionada. A falha na condição if dentro desse bloco não resultará em outras verificações de correspondência da expressão match original serem consideradas.
• Você pode usar as variáveis definidas no padrão em sua expressão if.
• A condição definida na guarda se aplica a todas as expressões em um padrão com um |.

Depois de ver os exercícios, você pode ver as soluções fornecidas.

• Mencione que uma String é suportada por um Vec, portanto ela tem um tamanho e capacidade e pode crescer se for mutável por meio de realocação no heap.

• Se os alunos perguntarem sobre isso, você pode mencionar que a memória subjacente é alocada no heap usando o System Allocator e os alocadores personalizados podem ser implementados usando a API Allocator.

• Podemos inspecionar o layout da memória com código inseguro (unsafe). No entanto, você deve apontar que isso é legitimamente inseguro!

  fn main() {
      let mut s1 = String::from("Olá");
      s1.push(' ');
      s1.push_str("mundo");
      // DON'T DO THIS AT HOME! For educational purposes only.
      // String provides no guarantees about its layout, so this could lead to
      // undefined behavior.
      unsafe {
          let (ptr, capacity, len): (usize, usize, usize) = std::mem::transmute(s1);
          println!("Ponteiro = {ptr:#x}, tamanho = {len}, capacidade = {capacity}");
      }
  }

• Neste ponto, se perguntado como, você pode mencionar que em Rust isso geralmente é tratado por wrappers (invólucros) RAII tais como Box, Vec, Rc ou Arc. Eles encapsulam a propriedade (ownership) e a alocação de memória por vários meios e previnem os erros possíveis em C.

• Aqui você pode ser perguntado sobre destrutores, o trait Drop é o equivalente em Rust.

• Mencione que isso é o oposto dos defaults (padrões) em C++, que copia por valor, a menos que você use std::move (e seu construtor esteja definido!).

• Apenas o ownership é movido. A geração de código de máquina para manipular os dados é uma questão de otimização, e essas cópias são agressivamente otimizadas.

• Valores simples (tais como inteiros) podem ser marcados como Copy (cópia) (veja slides mais adiante).

• No Rust, clones são explícitos (utilizando-se clone).

• Com a primeira chamada para diga_ola, main desiste da ownership de nome. Depois disso, nome não pode mais ser usado dentro de main.
• A memória do heap alocada para name será liberada no final da função say_hello.
• main pode manter a ownership se passar nome como uma referência (&name) e se say_hello aceitar uma referência como um parâmetro.
• Alternativamente, main pode passar um clone de nome na primeira chamada (name.clone()).
• Rust torna mais difícil a criação de cópias inadvertidamente do que o C++, tornando padrão a semântica de movimento e forçando os programadores a tornar os clones explícitos.

Copia e clonagem não são a mesma coisa:

• Cópia refere-se a cópias bit a bit de regiões de memória e não funciona em objetos arbitrários.
• Cópia não permite lógica personalizada (ao contrário dos construtores de cópia em C++).
• Clonagem é uma operação mais geral e também permite um comportamento personalizado através da implementação do trait Clone.
• Cópia não funciona em tipos que implementam o trait Drop.

No exemplo acima, tente o seguinte:

• Adicione um campo String ao struct Point. Ele não irá compilar porque String não é um tipo Copy.
• Remova Copy do atributo derive. O erro do compilador agora está no println! para p1.
• Mostre que ele funciona se ao invés disso você clonar p1.

Se os alunos perguntarem sobre derive, basta dizer que isto é uma forma de gerar código em Rust em tempo de compilação. Nesse caso, as implementações padrão dos traits Copy e Clone são geradas.

Notas sobre os retornos da pilha:

• Demonstre que o retorno de somar é barato porque o compilador pode eliminar a operação de cópia. Modifique o código acima para imprimir endereços da pilha e execute-o no Playground ou veja o código assembly em Godbolt. No nível de otimização “DEBUG”, os endereços devem mudar, enquanto eles permanecem os mesmos quando a configuração é alterada para “RELEASE”:

  #[derive(Debug)]
  struct Point(i32, i32);
  
  fn add(p1: &Point, p2: &Point) -> Point {
      let p = Point(p1.0 + p2.0, p1.1 + p2.1);
      println!("&p.0: {:p}", &p.0);
      p
  }
  
  pub fn main() {
      let p1 = Point(3, 4);
      let p2 = Point(10, 20);
      let p3 = add(&p1, &p2);
      println!("&p3.0: {:p}", &p3.0);
      println!("{p1:?} + {p2:?} = {p3:?}");
  }

• O compilador Rust pode fazer otimização de valor de retorno (Return Value Operation - RVO).

• Em C++, a elisão (omissão) de cópia deve ser definida na especificação da linguagem porque os construtores podem ter efeitos colaterais. Em Rust, isso não é um problema. Se o RVO não aconteceu, o Rust sempre executará uma cópia memcpy simples e eficiente.

• O código acima não compila porque a é emprestado como mutável (através de c) e como imutável (através de b) ao mesmo tempo.
• Mova a instrução println! para b antes do escopo que introduz c para fazer o código compilar.
• Após essa alteração, o compilador percebe que b só é usado antes do novo empréstimo mutável de a através de c. Este é um recurso do verificador de empréstimo (borrow checker) chamado “tempos de vida não lexicais”.

No exemplo acima, tente o seguinte:

• Mova a declaração de p2 e p3 para um novo escopo ({ ... }), resultando no seguinte código:

  #[derive(Debug)]
  struct Point(i32, i32);
  
  fn left_most<'a>(p1: &'a Point, p2: &'a Point) -> &'a Point {
      if p1.0 < p2.0 { p1 } else { p2 }
  }
  
  fn main() {
      let p1: Point = Point(10, 10);
      let p3: &Point;
      {
          let p2: Point = Point(20, 20);
          p3 = left_most(&p1, &p2);
      }
      println!("Ponto mais à esquerda: {:?}", p3);
  }

  Note como isto não compila uma vez que p3 vive mais que p2.

• Reinicie o espaço de trabalho e altere a assinatura da função para fn left_most<'a, 'b>(p1: &'a Point, p2: &'a Point) -> &'b Point. Isso não será compilado porque a relação entre os tempos de vida 'a e 'b não é clara.

• Outra forma de explicar:

  • Duas referências a dois valores são emprestadas por uma função e a função retorna outra referência.
  • Ela deve ter vindo de uma dessas duas entradas (ou de uma variável global).
  • De qual? O compilador precisa saber, de forma que no local da chamada a referência retornada não seja usada por mais tempo do que uma variável de onde veio a referência.

• No exemplo acima, a anotação em Highlight impõe que os dados subjacentes ao &str contido vivam pelo menos tanto quanto qualquer instância de Highlight que use esses dados.
• Se text for consumido antes do final do tempo de vida de fox (ou dog), o verificador de empréstimo lançará um erro.
• Tipos com dados emprestados forçam os usuários a manter os dados originais. Isso pode ser útil para criar exibições leves, mas geralmente as tornam um pouco mais difíceis de usar.
• Quando possível, faça com que as estruturas de dados possuam (own) seus dados diretamente.
• Algumas structs com múltiplas referências internas podem ter mais de uma anotação de tempo de vida. Isso pode ser necessário se houver a necessidade de descrever-se relacionamentos de tempo de vida entre as próprias referências, além do tempo de vida da própria struct. Esses são casos de uso bastante avançados.

Depois de ver os exercícios, você pode ver as soluções fornecidas.

Soluções

Pontos Chave:

• Structs funcionam como em C ou C++.
  • Como em C++, e ao contrário de C, nenhum typedef é necessário para definir um tipo.
  • Ao contrário do C++, não há herança entre structs.
• Os métodos são definidos em um bloco impl, que veremos nos próximos slides.
• Este pode ser um bom momento para que as pessoas saibam que existem diferentes tipos de structs.
  • Structs de tamanho zero por exemplo, struct Foo; podem ser usadas ao implementar uma característica em algum tipo, mas não possuem nenhum dado que você deseja armazenar nelas.
  • O próximo slide apresentará as estruturas tuplas (Estruturas Tupla) usadas quando o nome dos campos não são importantes.
• A sintaxe ..pedro permite copiar a maioria dos campos de uma struct sem precisar explicitar seus tipos. Sempre deve ser o último elemento.

• Newtypes são uma ótima maneira de codificar informações adicionais sobre o valor em um tipo primitivo, por exemplo:
  • O número é medido em algumas unidades: Newtons no exemplo acima.
  • O valor passou por alguma validação quando foi criado, então não é preciso validá-lo novamente a cada uso: NumeroTelefone(String) ou NumeroImpar(u32).
• Demonstre como somar um valor f64 em um valor do tipo Newtons acessando o campo único no newtype.
  • Geralmente, Rust não gosta de coisas implícitas, como unwrapping automático ou, por exemplo, usar booleanos como inteiros.
  • Sobrecarga de operadores é discutido no Dia 3 (generics).
• O examplo é uma referência sutil a falha do Orbitador Climático de Marte.

• A função new poderia ser escrita utilizando Self como tipo, já que ele é intercambiável com o nome da struct

  #[derive(Debug)]
  struct Person {
      name: String,
      age: u8,
  }
  impl Person {
      fn new(name: String, age: u8) -> Self {
          Self { name, age }
      }
  }

• Implemente a trait Default (Padrão) para a struct. Defina alguns campos e utilize valores padrão para os demais.

  #[derive(Debug)]
  struct Person {
      name: String,
      age: u8,
  }
  impl Default for Person {
      fn default() -> Person {
          Person {
              name: "Robô".to_string(),
              age: 0,
          }
      }
  }
  fn create_default() {
      let tmp = Person {
          ..Person::default()
      };
      let tmp = Person {
          name: "Sam".to_string(),
          ..Person::default()
      };
  }

• Métodos são definidos no bloco impl.

• Use a sintaxe de atualização de estruturas para definir uma nova struct usando peter. Note que a variável peter não será mais acessível após.

• Utilize {:#?} para imprimir structs utilizando a representação de depuração (Debug).

Pontos Chave:

• Pode ser útil introduzir métodos comparando-os com funções.
  • Métodos são chamados em uma instância de um tipo (como struct ou enum), o primeiro parâmetro representa a instância como self.
  • Os desenvolvedores podem optar por usar métodos para aproveitar a sintaxe do receptor do método e ajudar a mantê-los mais organizados. Usando métodos, podemos manter todo o código de implementação em um local previsível.
• Destaque o uso da palavra-chave self, um receptor de método.
  • Mostre que é um termo abreviado para self:Self e talvez mostre como o nome da struct também poderia ser usado.
  • Explique que Self é um apelido de tipo para o tipo em que o bloco impl está e pode ser usado em qualquer outro lugar no bloco.
  • Observe como self é usado como outras Structs e a notação de ponto pode ser usada para se referir a campos individuais.
  • Este pode ser um bom momento para demonstrar como &self difere de self modificando o código e tentando executar dizer_ola duas vezes.
• Descreveremos a distinção entre os receptores de método a seguir.

Considere enfatizar “compartilhado e imutável” e “único e mutável”. Essas restrições sempre vêm juntos no Rust devido às regras do Borrow Checker (verificador de empréstimo), e self não é uma exceção. Não será possível referenciar uma struct de vários locais e chamar um método mutável (&mut self) nela.

Pontos Chave:

• Todos os quatro métodos aqui usam um receptor de método diferente.
  • Você pode apontar como isso muda o que a função pode fazer com os valores das variáveis e se/como ela pode ser usada novamente na main.
  • Você pode mostrar o erro que aparece ao tentar chamar encerrar duas vezes.
• Observe que, embora os receptores do método sejam diferentes, as funções não estáticas são chamadas da mesma maneira no corpo principal. Rust permite referenciar e desreferenciar automaticamente ao chamar métodos. Rust adiciona automaticamente &, *, muts para que esse objeto corresponda à assinatura do método.
• Você pode apontar que imprimir_voltas está usando um vetor e iterando sobre ele. Descreveremos os vetores com mais detalhes à tarde.

Depois de ver os exercícios, você pode ver as soluções fornecidas.

• Na verdade, o Rust contém várias camadas de Biblioteca Padrão: core, alloc e std.
• core inclui os tipos e funções mais básicos que não dependem de libc, alocador ou até mesmo a presença de um sistema operacional.
• alloc inclui tipos que requerem um alocador de heap global, como Vec, Box e Arc.
• Os aplicativos Rust embarcados geralmente usam apenas core e, às vezes, alloc.

• Option e Result são amplamente usados não apenas na biblioteca padrão.
• Option<&T> não tem nenhum custo adicional de espaço em comparação com &T.
• Result é o tipo padrão para implementar tratamento de erros, como veremos no Dia 3.
• binary_search retorna Result<usize, usize>.
  • Se encontrado, Result::Ok contém o índice onde o elemento foi encontrado.
  • Caso contrário, Result::Err contém o índice onde tal elemento deve ser inserido.

• String::new retorna uma nova string vazia, use String::with_capacity quando você sabe a quantidade de dados que você deseja colocar na string.
• String::len retorna o tamanho da String em bytes (que pode ser diferente de seu comprimento em caracteres).
• String::chars retorna um iterador com os caracteres de fato. Observe que um char pode ser diferente do que um humano considerará um “caracter” devido a agrupamentos de grafemas (grapheme clusters).
• Quando as pessoas se referem a strings, elas podem estar falando sobre &str ou String.
• Quando um tipo implementa Deref<Target = T>, o compilador permitirá que você transparentemente chame métodos de T.
  • String implementa Deref<Target = str> que, de forma transparente, dá acesso aos métodos de str.
  • Escreva e compare let s3 = s1.deref(); e let s3 = &*s1;.
• String é implementado como um wrapper em torno de um vetor de bytes, muitas das operações que você vê suportados em vetores também são suportadas em String, mas com algumas garantias extras.
• Compare as diferentes formas de indexar uma String:
  • Para um caracter usando s3.chars().nth(i).unwrap() onde i está dentro dos limites, fora dos limites.
  • Para uma substring usando s3[0..4], onde essa slice está nos limites dos caracteres ou não.

• Vec é um tipo de coleção, como String e HashMap. Os dados que ele contém são armazenados no heap. Isso significa que a quantidade de dados não precisa ser conhecida em tempo de compilação. Ela pode crescer ou encolher em tempo de execução.
• Observe como Vec<T> também é um tipo genérico, mas você não precisa especificar T explicitamente. Como sempre, com a inferência de tipos do Rust, T foi estabelecido durante a primeira chamada de push.
• vec![...] é uma macro canônica para usar em vez de Vec::new() e suporta a adição de elementos iniciais ao vetor.
• Para indexar o vetor, você usa [ ], mas uma exceção do tipo pânico (panic) será gerada se o índice estiver fora dos limites. Alternativamente, usando get você obterá um Option. A função pop removerá o último elemento.
• Mostre uma iteração sobre um vetor e alterando o valor: for e in &mut v { *e += 50; }

• HashMap não está definido no prelúdio e precisa ser incluído no escopo.

• Tente as seguintes linhas de código. A primeira linha verá se um livro está no hash map e, caso não esteja, retorna um valor alternativo. A segunda linha irá inserir o valor alternativo no hash map se o livro não for encontrado.

    let pc1 = page_counts
        .get("Harry Potter and the Sorcerer's Stone ")
        .unwrap_or(&336);
    let pc2 = page_counts
        .entry("The Hunger Games".to_string())
        .or_insert(374);

• Ao contrário de vec!, infelizmente não existe uma macro hashmap! padrão.

  • Entretanto, desde o Rust 1.56, o HashMap implementa From<[(K, V); N]>, o que nos permite inicializar facilmente um hash map a partir de uma matriz literal:

      let page_counts = HashMap::from([
        ("Harry Potter and the Sorcerer's Stone".to_string(), 336),
        ("The Hunger Games".to_string(), 374),
      ]);

• Alternativamente, o HashMap pode ser construído a partir de qualquer Iterator que produz tuplas de chave-valor.

• Estamos mostrando HashMap<String, i32>, e evite usar &str como chave para facilitar os exemplos. É claro que o uso de referências em coleções pode ser feito, mas isto pode levar a complicações com o verificador de empréstimos.

  • Tente remover to_string() do exemplo acima e veja se ele ainda compila. Onde você acha que podemos ter problemas?

• This type has several “method-specific” return types, such as std::collections::hash_map::Keys. These types often appear in searches of the Rust docs. Show students the docs for this type, and the helpful link back to the keys method.

• Box é parecido com std::unique_ptr em C++, exceto que ele é garantidamente não nulo.
• No exemplo acima, você pode até remover o * na instrução println! graças ao Deref.
• Uma Box é útil quando você:
  • Tem um tipo cujo tamanho não está disponível em tempo de compilação, mas o compilador Rust precisa saber o tamanho exato.
  • Precisa transferir o ownership de um grande volume de dados. Ao invés de copiar grandes volumes de dados na pilha, eles são armazenados usando uma Box no heap e apenas o ponteiro é movido.

• Se a Box não for usada e tentarmos incorporar uma List diretamente na List, o compilador não conseguiria calcular um tamanho fixo da struct na memória (List teria tamanho infinito) .

• Box resolve esse problema, pois tem o mesmo tamanho de um ponteiro normal e apenas aponta para o próximo elemento da List no heap.

• Remova o Box na definição de List e mostre o erro de compilação. “Recursive with indirection” (recursivo com indireção) é uma dica para que você talvez queira usar uma Box ou referência de alguma forma, ao invés de armazenar um valor diretamente.

• O contador do Rc garante que os seus valores contidos sejam válidos enquanto houver referências.
• Rc em Rust é como std::shared_ptr em C++.
• Rc::clone é barato: ele cria um ponteiro para a mesma alocação e aumenta a contagem de referência. Ele não faz um “clone profundo” (deep clone) e geralmente pode ser ignorado ao procurar problemas de desempenho no código.
• make_mut realmente clona o valor interno se necessário (“clone-on-write”) e retorna uma referência mutável.
• Use Rc::strong_count para verificar a contagem de referência.
• Rc::downgrade lhe fornece um objeto contador de referências “fraco” (weak)_ para criar ciclos que podem ser apropriadamente descartados (provavelmente combinados com RefCell, no próximo slide).

• Se estivéssemos usando Cell em vez de RefCell neste exemplo, teríamos que mover o Node para fora do Rc para enviar os filhos e, em seguida, movê-lo de volta. Isso é seguro porque sempre há um, valor não referenciado em cell, mas não é ergonômico.
• Para fazer qualquer coisa com um Node, você deve chamar um método RefCell, geralmente borrow ou borrow_mut.
• Demonstre que loops de referência podem ser criados adicionando root a subtree.children (não tente imprimi-lo!).
• Para demonstrar um pânico em tempo de execução, adicione um fn inc(&mut self) que incrementa self.value e chama o mesmo método em seus filhos. Isso criará um pânico na presença do loop de referência, com thread 'main' em pânico no 'já emprestado: BorrowMutError'.

• Pacotes (packages) fornecem funcionalidades e incluem um arquivo Cargo.toml que descreve como gerar um pacote com um ou mais crates.
• Crates são arvores de módulos, onde um crate binário cria um executável e um crate de biblioteca é compilado em uma biblioteca.
• Módulos definem organização, escopo e são o foco desta seção.

• Use a palavra reservada pub para tornar módulos públicos.

Adicionamente, existem especificadores pub(...) avançados para restringir o escopo de visibilidade pública.

• Veja a Referência Rust.
• A configuração de visibilidade pub(crate) é um padrão comum.
• Menos comum, você pode dar visibilidade para um caminho específico.
• Em todo caso, a visibilidade deve ser concedida a um módulo ancestral (e a todos os seus descendentes).

• Antes do Rust 2018, os módulos precisavam estar localizados em module/mod.rs ao invés de module.rs, e esta ainda é uma alternativa funcional para edições posteriores a 2018.

• A principal razão para introduzir nome_de_arquivo.rs como alternativa a nome_de_arquivo/mod.rs foi porque muitos arquivos denominados mod.rs podem ser difíceis de distinguir em IDEs.

• O aninhamento mais profundo pode usar pastas, mesmo que o módulo principal seja um arquivo:

  src/
  ├── main.rs
  ├── top_module.rs
  └── top_module/
      └── sub_module.rs
  

• O local no qual o Rust irá procurar por módulos pode ser alterado por meio de uma diretiva de compilador:

  #[path = "algum/caminho.rs"]
  mod some_module;

  Isto é útil, por exemplo, se você quiser colocar testes para um módulo em um arquivo chamado algum_modulo_teste.rs, semelhante à convenção em Go.

Depois de ver os exercícios, você pode ver as soluções fornecidas.

• Tente declarar uma nova variável let p = Point { x: 5, y: 10.0 };.

• Arrume o código para permitir pontos que tenham elementos de tipos diferentes.

• Pergunta: Por que T é especificado duas vezes em impl<T> Point<T> {}? Isso não é redundante?
  • Isso ocorre porque é uma seção de implementação genérica para tipo genérico. Eles são genéricos de forma independente.
  • Significa que esses métodos são definidos para qualquer T.
  • É possível escrever Impl Point<u32> { .. }.
    • Point ainda é genérico e você pode usar Point<f64>, mas os métodos neste bloco só estarão disponíveis para Point<u32>.

• Tipos que implementam um dado trait podem ter tamanhos diferentes. Isto torna impossível haver coisas como Vec<Pet> no exemplo anterior.
• dyn Pet é uma maneira de dizer ao compilador sobre um tipo de tamanho dinâmico que implementa Pet.
• No exemplo, pets possui fat pointers para objetos que implementam Pet. O fat pointer consiste em dois componentes, um ponteiro para o objeto propriamente dito e um ponteiro para a tabela de métodos virtuais para a implementação de Pet do objeto em particular.
• Compare estas saídas no exemplo anterior::

      println!("{} {}", std::mem::size_of::<Dog>(), std::mem::size_of::<Cat>());
      println!("{} {}", std::mem::size_of::<&Dog>(), std::mem::size_of::<&Cat>());
      println!("{}", std::mem::size_of::<&dyn Pet>());
      println!("{}", std::mem::size_of::<Box<dyn Pet>>());

• Traits podem especificar métodos pré-implementados (padrão) e métodos que os usuários são obrigados a implementar. Os métodos com implementações padrão podem contar com os métodos requeridos.

• Mova o método not_equals para um novo trait NotEquals.

• Faça Equals um super trait para NotEquals.

  trait NotEquals: Equals {
      fn not_equals(&self, other: &Self) -> bool {
          !self.equals(other)
      }
  }

• Forneça uma implementação geral de NotEquals para Equals.

  trait NotEquals {
      fn not_equals(&self, other: &Self) -> bool;
  }
  
  impl<T> NotEquals for T where T: Equals {
      fn not_equals(&self, other: &Self) -> bool {
          !self.equals(other)
      }
  }

  • Com a implementação geral, você não precisa mais de Equals como um super trait para NotEqual.

Mostre uma cláusula where, os estudantes irão encontrá-la quando lerem código.

fn duplicate<T>(a: T) -> (T, T)
where
    T: Clone,
{
    (a.clone(), a.clone())
}

• Organiza a assinatura da função se você tiver muitos parâmetros.
• Possui recursos adicionais tornando-o mais poderoso.
  • Se alguém perguntar, o recurso extra é que o tipo à esquerda de “:” pode ser arbitrário, como Option<T>.

O significado do trait impl é um pouco difere de acordo com sua posição.

• For a parameter, impl Trait is like an anonymous generic parameter with a trait bound.

• For a return type, it means that the return type is some concrete type that implements the trait, without naming the type. This can be useful when you don’t want to expose the concrete type in a public API.

  Inference is hard in return position. A function returning impl Foo picks the concrete type it returns, without writing it out in the source. A function returning a generic type like collect<B>() -> B can return any type satisfying B, and the caller may need to choose one, such as with let x: Vec<_> = foo.collect() or with the turbofish, foo.collect::<Vec<_>>().

Este exemplo é ótimo, porque usa impl Display duas vezes. Isso ajuda a explicar que nada impõe que, nos dois usos, impl Display seja do mesmo tipo. Se usássemos um único T: Display, imporia a restrição de que o tipo T de entrada e o tipo T de retorno são do mesmo tipo. Isso não funcionaria para esta função específica, pois o tipo que esperamos como entrada provavelmente não é o que format! retorna. Se quiséssemos fazer o mesmo através da sintaxe : Display, precisaríamos de dois parâmetros genéricos independentes.

• The Iterator trait implements many common functional programming operations over collections (e.g. map, filter, reduce, etc). This is the trait where you can find all the documentation about them. In Rust these functions should produce the code as efficient as equivalent imperative implementations.

• IntoIterator is the trait that makes for loops work. It is implemented by collection types such as Vec<T> and references to them such as &Vec<T> and &[T]. Ranges also implement it. This is why you can iterate over a vector with for i in some_vec { .. } but some_vec.next() doesn’t exist.

Iterator implementa fn collect<B>(self) -> B where B: FromIterator<Self::Item>, Self: Sized

Também existem implementações que permitem fazer coisas legais como converter um Iterator<Item = Result<V, E>> em um Result<Vec<V>, E>.

• É por isso que é comum implementar apenas From, já que seu tipo também receberá a implementação de Into.
• Ao declarar um tipo de entrada de argumento de função como “qualquer coisa que possa ser convertida em String”, a regra é oposta, você deve usar Into. Sua função aceitará tipos que implementam From e aqueles que apenas implementam Into.

Pontos de discussão:

• Por que Drop::drop não recebe self?
  • Resposta curta: Se recebesse, std::mem::drop seria chamado no final do bloco, resultando em outra chamada para Drop::drop ocasionando um estouro de pilha.
• Tente substituir drop(a) por a.drop().

• Ele pode ser implementado diretamente ou derivado usando #[derive(Default)].
• A implementação usando derive produz um valor onde todos os campos são preenchidos com seus valores padrão.
  • Consequentemente, todos os tipos usados na estrutuda devem implementar Default também.
• Frequentemente, os tipos padrão do Rust implementam Default com valores razoáveis (ex: 0, "", etc).
• A cópia parcial de estrututas funciona bem em conjunto com default.
• A bilioteca padrão do Rust sabe que tipos podem implementar o trait Default e, convenientemente, provê métodos para isso.
• the .. syntax is called struct update syntax

Pontos de discussão:

• You could implement Add for &Point. In which situations is that useful?
  • Answer: Add:add consumes self. If type T for which you are overloading the operator is not Copy, you should consider overloading the operator for &T as well. This avoids unnecessary cloning on the call site.
• Why is Output an associated type? Could it be made a type parameter of the method?
  • Short answer: Function type parameters are controlled by the caller, but associated types (like Output) are controlled by the implementor of a trait.
• You could implement Add for two different types, e.g. impl Add<(i32, i32)> for Point would add a tuple to a Point.

Um Fn não consome nem muda os valores capturados ou talvez não capture nada, então, pode ser chamado várias vezes simultaneamente.

Um FnMut pode alterar os valores capturados, então você pode chamá-lo várias vezes, mas não simultaneamente.

Se você tiver um FnOnce, poderá chamá-lo apenas uma vez. Pode consumir os valores capturados.

FnMut é um subtipo de FnOnce. Fn é um subtipo de FnMut e FnOnce. Ou seja você pode usar um FnMut sempre que um FnOnce é chamado e você pode usar um Fn sempre que um FnMut ou um FnOnce é chamado.

The compiler also infers Copy (e.g. for add_3) and Clone (e.g. multiply_sum), depending on what the closure captures.

By default, closures will capture by reference if they can. The move keyword makes them capture by value.

fn make_greeter(prefix: String) -> impl Fn(&str) {
    return move |name| println!("{} {}", prefix, name)
}

fn main() {
    let hi = make_greeter("Hi".to_string());
    hi("there");
}

Depois de ver os exercícios, você pode ver as soluções fornecidas.

Como as assinaturas dos métodos estão faltando nas declarações do problema, a parte principal do exercício é especificá-las corretamente. Não é preciso modificar os testes.

Outras partes interessante do exercício:

• Derive um trait Copy para algumas structs, já que em testes os métodos às vezes não emprestam seus argumentos.
• Descubra que o trait Add deve ser implementado para que dois objetos sejam adicionados via “+”. Note que nós não discutimos generics até o Dia 3.

• Como em Option, o valor bem-sucedido fica dentro de Result, forçando o desenvolvedor a extraí-lo explicitamente. Isso encoraja a verificação de erros. No caso em que um erro nunca deve acontecer, unwrap() ou expect() podem ser chamados, e isso também sinaliza a intenção do desenvolvedor.
• A documentação de Result é uma leitura recomendada. Não durante o curso, mas vale a pena mencioná-la. Ele contém muitos métodos e funções de conveniência que ajudam na programação ao estilo funcional.

Pontos chave:

• A variável nome_usuario pode ser Ok(string) ou Err(error).
• Use a chamada fs::write para testar os diferentes cenários: nenhum arquivo, arquivo vazio e arquivo com nome de usuário.
• The return type of the function has to be compatible with the nested functions it calls. For instance, a function returning a Result<T, Err> can only apply the ? operator on a function returning a Result<AnyT, Err>. It cannot apply the ? operator on a function returning an Option<AnyT> or Result<T, OtherErr> unless OtherErr implements From<Err>. Reciprocally, a function returning an Option<T> can only apply the ? operator on a function returning an Option<AnyT>.
  • You can convert incompatible types into one another with the different Option and Result methods such as Option::ok_or, Result::ok, Result::err.

Pontos chave:

• A variável nome_usuario pode ser Ok(string) ou Err(error).
• Use a chamada fs::write para testar os diferentes cenários: nenhum arquivo, arquivo vazio e arquivo com nome de usuário.

É uma boa prática para todos os tipos de erro que não precisam ser no_std implementar std::error::Error, que requer Debug e Display. O crate Error para core só está disponível em nightly, então ainda não é totalmente compatível com no_std.

Geralmente é útil para eles implementar Clone e Eq também quando possível, para tornar mais fácil a vida para testes e consumidores da sua biblioteca. Neste caso, não podemos fazê-lo facilmente, porque io::Error não os implementa.

A derive macro thiserror implementa automaticamente std::error::Error, e opcionalmente, Display (se os atributos #[error(...)] forem fornecidos) e From (se o atributo #[from] for adicionado). Também funciona para structs.

Não afeta sua API pública, o que a torna boa para bibliotecas.

Isso economiza código, mas abre mão da capacidade de lidar com diferentes casos de erro de maneira diferenciada no programa. Como tal, geralmente não é uma boa ideia usar Box<dyn Error> na API pública de uma biblioteca, mas pode ser uma boa opção em um programa onde você deseja apenas exibir a mensagem de erro em algum lugar.

• anyhow::Result<V> é um apelido de tipo para Result<V, anyhow::Error>.
• anyhow::Error é essencialmente um wrapper em torno de Box<dyn Error>. Como tal, geralmente não é uma boa escolha para a API pública de uma biblioteca, mas é amplamente utilizado em aplicações.
• O tipo de erro real dentro dele pode ser extraído para exame, se necessário.
• A funcionalidade fornecida por anyhow::Result<T> pode ser familiar para desenvolvedores Go, pois fornece padrões de uso e ergonomia semelhantes a (T, error) de Go.

Rust inseguro não significa que o código esteja incorreto. Significa que os desenvolvedores desligaram os recursos de segurança do compilador e precisam escrever o código corretamente por eles mesmos. Significa também que o compilador não impõe mais as regras de segurança de memória do Rust.

É uma boa prática (e exigida pelo guia de estilo do Android Rust) escrever um comentário para cada bloco unsafe explicando como o código dentro dele satisfaz os requisitos de segurança para a operação insegura que está fazendo.

No caso de desreferência de ponteiros, isso significa que os ponteiros devem ser válidos, ou seja:

• O ponteiro deve ser não nulo.
• O ponteiro deve ser desreferenciável (dentro dos limites de um único objeto alocado).
• O objeto não deve ter sido desalocado.
• Não deve haver acessos simultâneos à mesma localização.
• Se o ponteiro foi obtido lançando uma referência, o objeto subjacente deve estar válido e nenhuma referência pode ser usada para acessar a memória.

Na maioria dos casos, o ponteiro também deve estar alinhado corretamente.

Usar uma variável estática mutável geralmente é uma má ideia, mas há alguns casos em que isso pode fazer sentido, tais como em código no_std de baixo nível, como implementar um alocador de heap ou trabalhar com algumas APIs C.

Unions raramente são necessárias no Rust, pois geralmente você pode usar um enum. Elas são ocasionalmente necessárias para interagir com as APIs da biblioteca C.

Se você deseja apenas reinterpretar os bytes como um tipo diferente, você provavelmente deveria usar std::mem::transmute ou um wrapper seguro como o crate zerocopy.

Na verdade, não usaríamos ponteiros para essa operação porque isso pode ser feito com segurança usando referências.

Observe que o código inseguro é permitido dentro de uma função insegura sem o uso de um bloco unsafe. Podemos proibir isso com #[deny(unsafe_op_in_unsafe_fn)]. Tente adicioná-lo e veja o que acontece.

Normalmente isso é apenas um problema para funções externas que fazem coisas com ponteiros que podem violar o modelo de memória do Rust, mas em geral qualquer função C pode ter comportamento indefinido sob quaisquer circunstâncias arbitrárias.

O "C" neste exemplo é o ABI; outros ABIs também estão disponíveis.

Deve haver uma seção # Safety no Rustdoc para o trait explicando os requisitos para ser implementado com segurança.

Na verdade, a seção de segurança para AsBytes é bem mais longa e complicada.

Os traits integrados Send e Sync são inseguros.

Depois de ver o exercício, você pode ver a solução fornecida.

#[no_mangle] desativa a alteração de name usual do Rust, então o símbolo exportado será apenas o nome da função. Você também pode usar #[export_name = "some_name"] para especificar qualquer nome que desejar.

• At this point, the instructor should switch to the CXX tutorial.

• Walk the students through the tutorial step by step.

• Highlight how CXX presents a clean interface without unsafe code in both languages.

• Show the correspondence between Rust and C++ types:

  • Explain how a Rust String cannot map to a C++ std::string (the latter does not uphold the UTF-8 invariant). Show that despite being different types, rust::String in C++ can be easily constructed from a C++ std::string, making it very ergonomic to use.

  • Explain that a Rust function returning Result<T, E> becomes a function which throws a E exception in C++ (and vice versa).

Nenhuma solução é fornecida aqui, pois isso é aberto: depende de você ter uma classe tendo um pedaço de código que você pode transformar em Rust em tempo real.

• HashMap depends on RNG.
• std re-exports the contents of both core and alloc.

• This will compile to an empty binary.
• std provides a panic handler; without it we must provide our own.
• It can also be provided by another crate, such as panic-halt.
• Depending on the target, you may need to compile with panic = "abort" to avoid an error about eh_personality.
• Note that there is no main or any other entry point; it’s up to you to define your own entry point. This will typically involve a linker script and some assembly code to set things up ready for Rust code to run.

• buddy_system_allocator is a third-party crate implementing a basic buddy system allocator. Other crates are available, or you can write your own or hook into your existing allocator.
• The const parameter of LockedHeap is the max order of the allocator; i.e. in this case it can allocate regions of up to 2**32 bytes.
• If any crate in your dependency tree depends on alloc then you must have exactly one global allocator defined in your binary. Usually this is done in the top-level binary crate.
• extern crate panic_halt as _ is necessary to ensure that the panic_halt crate is linked in so we get its panic handler.
• This example will build but not run, as it doesn’t have an entry point.

• The cortex_m_rt::entry macro requires that the function have type fn() -> !, because returning to the reset handler doesn’t make sense.
• Run the example with cargo embed --bin minimal

• GPIO 0 pin 21 is connected to the first column of the LED matrix, and pin 28 to the first row.

Run the example with:

cargo embed --bin mmio

• SVD (System View Description) files are XML files typically provided by silicon vendors which describe the memory map of the device.
  • They are organised by peripheral, register, field and value, with names, descriptions, addresses and so on.
  • SVD files are often buggy and incomplete, so there are various projects which patch the mistakes, add missing details, and publish the generated crates.
• cortex-m-rt provides the vector table, among other things.
• If you cargo install cargo-binutils then you can run cargo objdump --bin pac -- -d --no-show-raw-insn to see the resulting binary.

Run the example with:

cargo embed --bin pac

• set_low and set_high are methods on the embedded_hal OutputPin trait.
• HAL crates exist for many Cortex-M and RISC-V devices, including various STM32, GD32, nRF, NXP, MSP430, AVR and PIC microcontrollers.

Run the example with:

cargo embed --bin hal

• In this case the board support crate is just providing more useful names, and a bit of initialisation.
• The crate may also include drivers for some on-board devices outside of the microcontroller itself.
  • microbit-v2 includes a simple driver for the LED matrix.

Run the example with:

cargo embed --bin board_support

• Pins don’t implement Copy or Clone, so only one instance of each can exist. Once a pin is moved out of the port struct nobody else can take it.
• Changing the configuration of a pin consumes the old pin instance, so you can’t keep use the old instance afterwards.
• The type of a value indicates the state that it is in: e.g. in this case, the configuration state of a GPIO pin. This encodes the state machine into the type system, and ensures that you don’t try to use a pin in a certain way without properly configuring it first. Illegal state transitions are caught at compile time.
• You can call is_high on an input pin and set_high on an output pin, but not vice-versa.
• Many HAL crates follow this pattern.

• There are implementations for many microcontrollers, as well as other platforms such as Linux on Raspberry Pi.
• There is work in progress on an async version of embedded-hal, but it isn’t stable yet.

• CMSIS-DAP is an Arm standard protocol over USB for an in-circuit debugger to access the CoreSight Debug Access Port of various Arm Cortex processors. It’s what the on-board debugger on the BBC micro:bit uses.
• ST-Link is a range of in-circuit debuggers from ST Microelectronics, J-Link is a range from SEGGER.
• The Debug Access Port is usually either a 5-pin JTAG interface or 2-pin Serial Wire Debug.
• probe-rs is a library which you can integrate into your own tools if you want to.
• The Microsoft Debug Adapter Protocol lets VSCode and other IDEs debug code running on any supported microcontroller.
• cargo-embed is a binary built using the probe-rs library.
• RTT (Real Time Transfers) is a mechanism to transfer data between the debug host and the target through a number of ringbuffers.

In GDB, try running:

b src/bin/board_support.rs:29
b src/bin/board_support.rs:30
b src/bin/board_support.rs:32
c
c
c

• RTIC can be considered either an RTOS or a concurrency framework.
  • It doesn’t include any HALs.
  • It uses the Cortex-M NVIC (Nested Virtual Interrupt Controller) for scheduling rather than a proper kernel.
  • Cortex-M only.
• Google uses TockOS on the Haven microcontroller for Titan security keys.
• FreeRTOS is mostly written in C, but there are Rust bindings for writing applications.

Depois de ver os exercícios, você pode ver as soluções fornecidas.

• Broadly speaking, microcontrollers don’t have an MMU or multiple levels of privilege (exception levels on Arm CPUs, rings on x86), while application processors do.
• QEMU supports emulating various different machines or board models for each architecture. The ‘virt’ board doesn’t correspond to any particular real hardware, but is designed purely for virtual machines.

• This is the same as it would be for C: initialising the processor state, zeroing the BSS, and setting up the stack pointer.
  • The BSS (block starting symbol, for historical reasons) is the part of the object file which containing statically allocated variables which are initialised to zero. They are omitted from the image, to avoid wasting space on zeroes. The compiler assumes that the loader will take care of zeroing them.
• The BSS may already be zeroed, depending on how memory is initialised and the image is loaded, but we zero it to be sure.
• We need to enable the MMU and cache before reading or writing any memory. If we don’t:
  • Unaligned accesses will fault. We build the Rust code for the aarch64-unknown-none target which sets +strict-align to prevent the compiler generating unaligned accesses, so it should be fine in this case, but this is not necessarily the case in general.
  • If it were running in a VM, this can lead to cache coherency issues. The problem is that the VM is accessing memory directly with the cache disabled, while the host has cachable aliases to the same memory. Even if the host doesn’t explicitly access the memory, speculative accesses can lead to cache fills, and then changes from one or the other will get lost when the cache is cleaned or the VM enables the cache. (Cache is keyed by physical address, not VA or IPA.)
• For simplicity, we just use a hardcoded pagetable (see idmap.S) which identity maps the first 1 GiB of address space for devices, the next 1 GiB for DRAM, and another 1 GiB higher up for more devices. This matches the memory layout that QEMU uses.
• We also set up the exception vector (vbar_el1), which we’ll see more about later.
• All examples this afternoon assume we will be running at exception level 1 (EL1). If you need to run at a different exception level you’ll need to modify entry.S accordingly.

• PSCI is the Arm Power State Coordination Interface, a standard set of functions to manage system and CPU power states, among other things. It is implemented by EL3 firmware and hypervisors on many systems.
• The 0 => _ syntax means initialise the register to 0 before running the inline assembly code, and ignore its contents afterwards. We need to use inout rather than in because the call could potentially clobber the contents of the registers.
• This main function needs to be #[no_mangle] and extern "C" because it is called from our entry point in entry.S.
• _x0–_x3 are the values of registers x0–x3, which are conventionally used by the bootloader to pass things like a pointer to the device tree. According to the standard aarch64 calling convention (which is what extern "C" specifies to use), registers x0–x7 are used for the first 8 arguments passed to a function, so entry.S doesn’t need to do anything special except make sure it doesn’t change these registers.
• Run the example in QEMU with make qemu_psci under src/bare-metal/aps/examples.

• Volatile access: read or write operations may have side-effects, so prevent the compiler or hardware from reordering, duplicating or eliding them.
  • Usually if you write and then read, e.g. via a mutable reference, the compiler may assume that the value read is the same as the value just written, and not bother actually reading memory.
• Some existing crates for volatile access to hardware do hold references, but this is unsound. Whenever a reference exist, the compiler may choose to dereference it.
• Use the addr_of! macro to get struct field pointers from a pointer to the struct.

• Note that Uart::new is unsafe while the other methods are safe. This is because as long as the caller of Uart::new guarantees that its safety requirements are met (i.e. that there is only ever one instance of the driver for a given UART, and nothing else aliasing its address space), then it is always safe to call write_byte later because we can assume the necessary preconditions.
• We could have done it the other way around (making new safe but write_byte unsafe), but that would be much less convenient to use as every place that calls write_byte would need to reason about the safety
• This is a common pattern for writing safe wrappers of unsafe code: moving the burden of proof for soundness from a large number of places to a smaller number of places.

More traits

We derived the Debug trait. It would be useful to implement a few more traits too.

use core::fmt::{self, Write};

impl Write for Uart {
    fn write_str(&mut self, s: &str) -> fmt::Result {
        for c in s.as_bytes() {
            self.write_byte(*c);
        }
        Ok(())
    }
}

// Safe because it just contains a pointer to device memory, which can be
// accessed from any context.
unsafe impl Send for Uart {}

A better UART driver

The PL011 actually has a bunch more registers, and adding offsets to construct pointers to access them is error-prone and hard to read. Plus, some of them are bit fields which would be nice to access in a structured way.

Bitflags

The bitflags crate is useful for working with bitflags.

use bitflags::bitflags;

bitflags! {
    /// Flags from the UART flag register.
    #[repr(transparent)]
    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
    struct Flags: u16 {
        /// Clear to send.
        const CTS = 1 << 0;
        /// Data set ready.
        const DSR = 1 << 1;
        /// Data carrier detect.
        const DCD = 1 << 2;
        /// UART busy transmitting data.
        const BUSY = 1 << 3;
        /// Receive FIFO is empty.
        const RXFE = 1 << 4;
        /// Transmit FIFO is full.
        const TXFF = 1 << 5;
        /// Receive FIFO is full.
        const RXFF = 1 << 6;
        /// Transmit FIFO is empty.
        const TXFE = 1 << 7;
        /// Ring indicator.
        const RI = 1 << 8;
    }
}

Multiple registers

We can use a struct to represent the memory layout of the UART’s registers.

#[repr(C, align(4))]
struct Registers {
    dr: u16,
    _reserved0: [u8; 2],
    rsr: ReceiveStatus,
    _reserved1: [u8; 19],
    fr: Flags,
    _reserved2: [u8; 6],
    ilpr: u8,
    _reserved3: [u8; 3],
    ibrd: u16,
    _reserved4: [u8; 2],
    fbrd: u8,
    _reserved5: [u8; 3],
    lcr_h: u8,
    _reserved6: [u8; 3],
    cr: u16,
    _reserved7: [u8; 3],
    ifls: u8,
    _reserved8: [u8; 3],
    imsc: u16,
    _reserved9: [u8; 2],
    ris: u16,
    _reserved10: [u8; 2],
    mis: u16,
    _reserved11: [u8; 2],
    icr: u16,
    _reserved12: [u8; 2],
    dmacr: u8,
    _reserved13: [u8; 3],
}

Driver

Now let’s use the new Registers struct in our driver.

/// Driver for a PL011 UART.
#[derive(Debug)]
pub struct Uart {
    registers: *mut Registers,
}

impl Uart {
    /// Constructs a new instance of the UART driver for a PL011 device at the
    /// given base address.
    ///
    /// # Safety
    ///
    /// The given base address must point to the 8 MMIO control registers of a
    /// PL011 device, which must be mapped into the address space of the process
    /// as device memory and not have any other aliases.
    pub unsafe fn new(base_address: *mut u32) -> Self {
        Self {
            registers: base_address as *mut Registers,
        }
    }

    /// Writes a single byte to the UART.
    pub fn write_byte(&self, byte: u8) {
        // Wait until there is room in the TX buffer.
        while self.read_flag_register().contains(Flags::TXFF) {}

        // Safe because we know that self.registers points to the control
        // registers of a PL011 device which is appropriately mapped.
        unsafe {
            // Write to the TX buffer.
            addr_of_mut!((*self.registers).dr).write_volatile(byte.into());
        }

        // Wait until the UART is no longer busy.
        while self.read_flag_register().contains(Flags::BUSY) {}
    }

    /// Reads and returns a pending byte, or `None` if nothing has been received.
    pub fn read_byte(&self) -> Option<u8> {
        if self.read_flag_register().contains(Flags::RXFE) {
            None
        } else {
            let data = unsafe { addr_of!((*self.registers).dr).read_volatile() };
            // TODO: Check for error conditions in bits 8-11.
            Some(data as u8)
        }
    }

    fn read_flag_register(&self) -> Flags {
        // Safe because we know that self.registers points to the control
        // registers of a PL011 device which is appropriately mapped.
        unsafe { addr_of!((*self.registers).fr).read_volatile() }
    }
}

Using it

Let’s write a small program using our driver to write to the serial console, and echo incoming bytes.

#![no_main]
#![no_std]

mod exceptions;
mod pl011;

use crate::pl011::Uart;
use core::fmt::Write;
use core::panic::PanicInfo;
use log::error;
use smccc::psci::system_off;
use smccc::Hvc;

/// Base address of the primary PL011 UART.
const PL011_BASE_ADDRESS: *mut u32 = 0x900_0000 as _;

#[no_mangle]
extern "C" fn main(x0: u64, x1: u64, x2: u64, x3: u64) {
    // Safe because `PL011_BASE_ADDRESS` is the base address of a PL011 device,
    // and nothing else accesses that address range.
    let mut uart = unsafe { Uart::new(PL011_BASE_ADDRESS) };

    writeln!(uart, "main({x0:#x}, {x1:#x}, {x2:#x}, {x3:#x})").unwrap();

    loop {
        if let Some(byte) = uart.read_byte() {
            uart.write_byte(byte);
            match byte {
                b'\r' => {
                    uart.write_byte(b'\n');
                }
                b'q' => break,
                _ => {}
            }
        }
    }

    writeln!(uart, "Bye!").unwrap();
    system_off::<Hvc>().unwrap();
}

Gerando Registros (Log)

It would be nice to be able to use the logging macros from the log crate. We can do this by implementing the Log trait.

use crate::pl011::Uart;
use core::fmt::Write;
use log::{LevelFilter, Log, Metadata, Record, SetLoggerError};
use spin::mutex::SpinMutex;

static LOGGER: Logger = Logger {
    uart: SpinMutex::new(None),
};

struct Logger {
    uart: SpinMutex<Option<Uart>>,
}

impl Log for Logger {
    fn enabled(&self, _metadata: &Metadata) -> bool {
        true
    }

    fn log(&self, record: &Record) {
        writeln!(
            self.uart.lock().as_mut().unwrap(),
            "[{}] {}",
            record.level(),
            record.args()
        )
        .unwrap();
    }

    fn flush(&self) {}
}

/// Initialises UART logger.
pub fn init(uart: Uart, max_level: LevelFilter) -> Result<(), SetLoggerError> {
    LOGGER.uart.lock().replace(uart);

    log::set_logger(&LOGGER)?;
    log::set_max_level(max_level);
    Ok(())
}

Using it

We need to initialise the logger before we use it.

#![no_main]
#![no_std]

mod exceptions;
mod logger;
mod pl011;

use crate::pl011::Uart;
use core::panic::PanicInfo;
use log::{error, info, LevelFilter};
use smccc::psci::system_off;
use smccc::Hvc;

/// Base address of the primary PL011 UART.
const PL011_BASE_ADDRESS: *mut u32 = 0x900_0000 as _;

#[no_mangle]
extern "C" fn main(x0: u64, x1: u64, x2: u64, x3: u64) {
    // Safe because `PL011_BASE_ADDRESS` is the base address of a PL011 device,
    // and nothing else accesses that address range.
    let uart = unsafe { Uart::new(PL011_BASE_ADDRESS) };
    logger::init(uart, LevelFilter::Trace).unwrap();

    info!("main({x0:#x}, {x1:#x}, {x2:#x}, {x3:#x})");

    assert_eq!(x1, 42);

    system_off::<Hvc>().unwrap();
}

#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    error!("{info}");
    system_off::<Hvc>().unwrap();
    loop {}
}

Exceções

AArch64 defines an exception vector table with 16 entries, for 4 types of exceptions (synchronous, IRQ, FIQ, SError) from 4 states (current EL with SP0, current EL with SPx, lower EL using AArch64, lower EL using AArch32). We implement this in assembly to save volatile registers to the stack before calling into Rust code:

use log::error;
use smccc::psci::system_off;
use smccc::Hvc;

#[no_mangle]
extern "C" fn sync_exception_current(_elr: u64, _spsr: u64) {
    error!("sync_exception_current");
    system_off::<Hvc>().unwrap();
}

#[no_mangle]
extern "C" fn irq_current(_elr: u64, _spsr: u64) {
    error!("irq_current");
    system_off::<Hvc>().unwrap();
}

#[no_mangle]
extern "C" fn fiq_current(_elr: u64, _spsr: u64) {
    error!("fiq_current");
    system_off::<Hvc>().unwrap();
}

#[no_mangle]
extern "C" fn serr_current(_elr: u64, _spsr: u64) {
    error!("serr_current");
    system_off::<Hvc>().unwrap();
}

#[no_mangle]
extern "C" fn sync_lower(_elr: u64, _spsr: u64) {
    error!("sync_lower");
    system_off::<Hvc>().unwrap();
}

#[no_mangle]
extern "C" fn irq_lower(_elr: u64, _spsr: u64) {
    error!("irq_lower");
    system_off::<Hvc>().unwrap();
}

#[no_mangle]
extern "C" fn fiq_lower(_elr: u64, _spsr: u64) {
    error!("fiq_lower");
    system_off::<Hvc>().unwrap();
}

#[no_mangle]
extern "C" fn serr_lower(_elr: u64, _spsr: u64) {
    error!("serr_lower");
    system_off::<Hvc>().unwrap();
}

Other projects

• oreboot
  • “coreboot without the C”
  • Supports x86, aarch64 and RISC-V.
  • Relies on LinuxBoot rather than having many drivers itself.
• Rust RaspberryPi OS tutorial
  • Initialisation, UART driver, simple bootloader, JTAG, exception levels, exception handling, page tables
  • Some dodginess around cache maintenance and initialisation in Rust, not necessarily a good example to copy for production code.
• cargo-call-stack
  • Static analysis to determine maximum stack usage.

Crates Úteis para Testes

We’ll go over a few crates which solve some common problems in bare-metal programming.

zerocopy

The zerocopy crate (from Fuchsia) provides traits and macros for safely converting between byte sequences and other types.

use zerocopy::AsBytes;

#[repr(u32)]
#[derive(AsBytes, Debug, Default)]
enum RequestType {
    #[default]
    In = 0,
    Out = 1,
    Flush = 4,
}

#[repr(C)]
#[derive(AsBytes, Debug, Default)]
struct VirtioBlockRequest {
    request_type: RequestType,
    reserved: u32,
    sector: u64,
}

fn main() {
    let request = VirtioBlockRequest {
        request_type: RequestType::Flush,
        sector: 42,
        ..Default::default()
    };

    assert_eq!(
        request.as_bytes(),
        &[4, 0, 0, 0, 0, 0, 0, 0, 42, 0, 0, 0, 0, 0, 0, 0]
    );
}

This is not suitable for MMIO (as it doesn’t use volatile reads and writes), but can be useful for working with structures shared with hardware e.g. by DMA, or sent over some external interface.

aarch64-paging

The aarch64-paging crate lets you create page tables according to the AArch64 Virtual Memory System Architecture.

use aarch64_paging::{
    idmap::IdMap,
    paging::{Attributes, MemoryRegion},
};

const ASID: usize = 1;
const ROOT_LEVEL: usize = 1;

// Create a new page table with identity mapping.
let mut idmap = IdMap::new(ASID, ROOT_LEVEL);
// Map a 2 MiB region of memory as read-only.
idmap.map_range(
    &MemoryRegion::new(0x80200000, 0x80400000),
    Attributes::NORMAL | Attributes::NON_GLOBAL | Attributes::READ_ONLY,
).unwrap();
// Set `TTBR0_EL1` to activate the page table.
idmap.activate();

buddy_system_allocator

buddy_system_allocator is a third-party crate implementing a basic buddy system allocator. It can be used both for LockedHeap implementing GlobalAlloc so you can use the standard alloc crate (as we saw before), or for allocating other address space. For example, we might want to allocate MMIO space for PCI BARs:

use buddy_system_allocator::FrameAllocator;
use core::alloc::Layout;

fn main() {
    let mut allocator = FrameAllocator::<32>::new();
    allocator.add_frame(0x200_0000, 0x400_0000);

    let layout = Layout::from_size_align(0x100, 0x100).unwrap();
    let bar = allocator
        .alloc_aligned(layout)
        .expect("Failed to allocate 0x100 byte MMIO region");
    println!("Allocated 0x100 byte MMIO region at {:#x}", bar);
}

tinyvec

Sometimes you want something which can be resized like a Vec, but without heap allocation. tinyvec provides this: a vector backed by an array or slice, which could be statically allocated or on the stack, which keeps track of how many elements are used and panics if you try to use more than are allocated.

use tinyvec::{array_vec, ArrayVec};

fn main() {
    let mut numbers: ArrayVec<[u32; 5]> = array_vec!(42, 66);
    println!("{numbers:?}");
    numbers.push(7);
    println!("{numbers:?}");
    numbers.remove(1);
    println!("{numbers:?}");
}

spin

std::sync::Mutex and the other synchronisation primitives from std::sync are not available in core or alloc. How can we manage synchronisation or interior mutability, such as for sharing state between different CPUs?

The spin crate provides spinlock-based equivalents of many of these primitives.

use spin::mutex::SpinMutex;

static counter: SpinMutex<u32> = SpinMutex::new(0);

fn main() {
    println!("count: {}", counter.lock());
    *counter.lock() += 2;
    println!("count: {}", counter.lock());
}

Android

To build a bare-metal Rust binary in AOSP, you need to use a rust_ffi_static Soong rule to build your Rust code, then a cc_binary with a linker script to produce the binary itself, and then a raw_binary to convert the ELF to a raw binary ready to be run.

rust_ffi_static {
    name: "libvmbase_example",
    defaults: ["vmbase_ffi_defaults"],
    crate_name: "vmbase_example",
    srcs: ["src/main.rs"],
    rustlibs: [
        "libvmbase",
    ],
}

cc_binary {
    name: "vmbase_example",
    defaults: ["vmbase_elf_defaults"],
    srcs: [
        "idmap.S",
    ],
    static_libs: [
        "libvmbase_example",
    ],
    linker_scripts: [
        "image.ld",
        ":vmbase_sections",
    ],
}

raw_binary {
    name: "vmbase_example_bin",
    stem: "vmbase_example.bin",
    src: ":vmbase_example",
    enabled: false,
    target: {
        android_arm64: {
            enabled: true,
        },
    },
}

vmbase

For VMs running under crosvm on aarch64, the vmbase library provides a linker script and useful defaults for the build rules, along with an entry point, UART console logging and more.

#![no_main]
#![no_std]

use vmbase::{main, println};

main!(main);

pub fn main(arg0: u64, arg1: u64, arg2: u64, arg3: u64) {
    println!("Hello world");
}

Exercícios

We will write a driver for the PL031 real-time clock device.

RTC driver

The QEMU aarch64 virt machine has a PL031 real-time clock at 0x9010000. For this exercise, you should write a driver for it.

1. Use it to print the current time to the serial console. You can use the chrono crate for date/time formatting.
2. Use the match register and raw interrupt status to busy-wait until a given time, e.g. 3 seconds in the future. (Call core::hint::spin_loop inside the loop.)
3. Extension if you have time: Enable and handle the interrupt generated by the RTC match. You can use the driver provided in the arm-gic crate to configure the Arm Generic Interrupt Controller.
   • Use the RTC interrupt, which is wired to the GIC as IntId::spi(2).
   • Once the interrupt is enabled, you can put the core to sleep via arm_gic::wfi(), which will cause the core to sleep until it receives an interrupt.

Download the exercise template and look in the rtc directory for the following files.

src/main.rs:

#![no_main]
#![no_std]

mod exceptions;
mod logger;
mod pl011;

use crate::pl011::Uart;
use arm_gic::gicv3::GicV3;
use core::panic::PanicInfo;
use log::{error, info, trace, LevelFilter};
use smccc::psci::system_off;
use smccc::Hvc;

/// Base addresses of the GICv3.
const GICD_BASE_ADDRESS: *mut u64 = 0x800_0000 as _;
const GICR_BASE_ADDRESS: *mut u64 = 0x80A_0000 as _;

/// Base address of the primary PL011 UART.
const PL011_BASE_ADDRESS: *mut u32 = 0x900_0000 as _;

#[no_mangle]
extern "C" fn main(x0: u64, x1: u64, x2: u64, x3: u64) {
    // Safe because `PL011_BASE_ADDRESS` is the base address of a PL011 device,
    // and nothing else accesses that address range.
    let uart = unsafe { Uart::new(PL011_BASE_ADDRESS) };
    logger::init(uart, LevelFilter::Trace).unwrap();

    info!("main({:#x}, {:#x}, {:#x}, {:#x})", x0, x1, x2, x3);

    // Safe because `GICD_BASE_ADDRESS` and `GICR_BASE_ADDRESS` are the base
    // addresses of a GICv3 distributor and redistributor respectively, and
    // nothing else accesses those address ranges.
    let mut gic = unsafe { GicV3::new(GICD_BASE_ADDRESS, GICR_BASE_ADDRESS) };
    gic.setup();

    // TODO: Create instance of RTC driver and print current time.

    // TODO: Wait for 3 seconds.

    system_off::<Hvc>().unwrap();
}

#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    error!("{info}");
    system_off::<Hvc>().unwrap();
    loop {}
}

src/exceptions.rs (you should only need to change this for the 3rd part of the exercise):

#![allow(unused)]
fn main() {
// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

use arm_gic::gicv3::GicV3;
use log::{error, info, trace};
use smccc::psci::system_off;
use smccc::Hvc;

#[no_mangle]
extern "C" fn sync_exception_current(_elr: u64, _spsr: u64) {
    error!("sync_exception_current");
    system_off::<Hvc>().unwrap();
}

#[no_mangle]
extern "C" fn irq_current(_elr: u64, _spsr: u64) {
    trace!("irq_current");
    let intid = GicV3::get_and_acknowledge_interrupt().expect("No pending interrupt");
    info!("IRQ {intid:?}");
}

#[no_mangle]
extern "C" fn fiq_current(_elr: u64, _spsr: u64) {
    error!("fiq_current");
    system_off::<Hvc>().unwrap();
}

#[no_mangle]
extern "C" fn serr_current(_elr: u64, _spsr: u64) {
    error!("serr_current");
    system_off::<Hvc>().unwrap();
}

#[no_mangle]
extern "C" fn sync_lower(_elr: u64, _spsr: u64) {
    error!("sync_lower");
    system_off::<Hvc>().unwrap();
}

#[no_mangle]
extern "C" fn irq_lower(_elr: u64, _spsr: u64) {
    error!("irq_lower");
    system_off::<Hvc>().unwrap();
}

#[no_mangle]
extern "C" fn fiq_lower(_elr: u64, _spsr: u64) {
    error!("fiq_lower");
    system_off::<Hvc>().unwrap();
}

#[no_mangle]
extern "C" fn serr_lower(_elr: u64, _spsr: u64) {
    error!("serr_lower");
    system_off::<Hvc>().unwrap();
}
}

src/logger.rs (you shouldn’t need to change this):

#![allow(unused)]
fn main() {
// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// ANCHOR: main
use crate::pl011::Uart;
use core::fmt::Write;
use log::{LevelFilter, Log, Metadata, Record, SetLoggerError};
use spin::mutex::SpinMutex;

static LOGGER: Logger = Logger {
    uart: SpinMutex::new(None),
};

struct Logger {
    uart: SpinMutex<Option<Uart>>,
}

impl Log for Logger {
    fn enabled(&self, _metadata: &Metadata) -> bool {
        true
    }

    fn log(&self, record: &Record) {
        writeln!(
            self.uart.lock().as_mut().unwrap(),
            "[{}] {}",
            record.level(),
            record.args()
        )
        .unwrap();
    }

    fn flush(&self) {}
}

/// Initialises UART logger.
pub fn init(uart: Uart, max_level: LevelFilter) -> Result<(), SetLoggerError> {
    LOGGER.uart.lock().replace(uart);

    log::set_logger(&LOGGER)?;
    log::set_max_level(max_level);
    Ok(())
}
}

src/pl011.rs (you shouldn’t need to change this):

#![allow(unused)]
fn main() {
// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#![allow(unused)]

use core::fmt::{self, Write};
use core::ptr::{addr_of, addr_of_mut};

// ANCHOR: Flags
use bitflags::bitflags;

bitflags! {
    /// Flags from the UART flag register.
    #[repr(transparent)]
    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
    struct Flags: u16 {
        /// Clear to send.
        const CTS = 1 << 0;
        /// Data set ready.
        const DSR = 1 << 1;
        /// Data carrier detect.
        const DCD = 1 << 2;
        /// UART busy transmitting data.
        const BUSY = 1 << 3;
        /// Receive FIFO is empty.
        const RXFE = 1 << 4;
        /// Transmit FIFO is full.
        const TXFF = 1 << 5;
        /// Receive FIFO is full.
        const RXFF = 1 << 6;
        /// Transmit FIFO is empty.
        const TXFE = 1 << 7;
        /// Ring indicator.
        const RI = 1 << 8;
    }
}
// ANCHOR_END: Flags

bitflags! {
    /// Flags from the UART Receive Status Register / Error Clear Register.
    #[repr(transparent)]
    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
    struct ReceiveStatus: u16 {
        /// Framing error.
        const FE = 1 << 0;
        /// Parity error.
        const PE = 1 << 1;
        /// Break error.
        const BE = 1 << 2;
        /// Overrun error.
        const OE = 1 << 3;
    }
}

// ANCHOR: Registers
#[repr(C, align(4))]
struct Registers {
    dr: u16,
    _reserved0: [u8; 2],
    rsr: ReceiveStatus,
    _reserved1: [u8; 19],
    fr: Flags,
    _reserved2: [u8; 6],
    ilpr: u8,
    _reserved3: [u8; 3],
    ibrd: u16,
    _reserved4: [u8; 2],
    fbrd: u8,
    _reserved5: [u8; 3],
    lcr_h: u8,
    _reserved6: [u8; 3],
    cr: u16,
    _reserved7: [u8; 3],
    ifls: u8,
    _reserved8: [u8; 3],
    imsc: u16,
    _reserved9: [u8; 2],
    ris: u16,
    _reserved10: [u8; 2],
    mis: u16,
    _reserved11: [u8; 2],
    icr: u16,
    _reserved12: [u8; 2],
    dmacr: u8,
    _reserved13: [u8; 3],
}
// ANCHOR_END: Registers

// ANCHOR: Uart
/// Driver for a PL011 UART.
#[derive(Debug)]
pub struct Uart {
    registers: *mut Registers,
}

impl Uart {
    /// Constructs a new instance of the UART driver for a PL011 device at the
    /// given base address.
    ///
    /// # Safety
    ///
    /// The given base address must point to the MMIO control registers of a
    /// PL011 device, which must be mapped into the address space of the process
    /// as device memory and not have any other aliases.
    pub unsafe fn new(base_address: *mut u32) -> Self {
        Self {
            registers: base_address as *mut Registers,
        }
    }

    /// Writes a single byte to the UART.
    pub fn write_byte(&self, byte: u8) {
        // Wait until there is room in the TX buffer.
        while self.read_flag_register().contains(Flags::TXFF) {}

        // Safe because we know that self.registers points to the control
        // registers of a PL011 device which is appropriately mapped.
        unsafe {
            // Write to the TX buffer.
            addr_of_mut!((*self.registers).dr).write_volatile(byte.into());
        }

        // Wait until the UART is no longer busy.
        while self.read_flag_register().contains(Flags::BUSY) {}
    }

    /// Reads and returns a pending byte, or `None` if nothing has been received.
    pub fn read_byte(&self) -> Option<u8> {
        if self.read_flag_register().contains(Flags::RXFE) {
            None
        } else {
            let data = unsafe { addr_of!((*self.registers).dr).read_volatile() };
            // TODO: Check for error conditions in bits 8-11.
            Some(data as u8)
        }
    }

    fn read_flag_register(&self) -> Flags {
        // Safe because we know that self.registers points to the control
        // registers of a PL011 device which is appropriately mapped.
        unsafe { addr_of!((*self.registers).fr).read_volatile() }
    }
}
// ANCHOR_END: Uart

impl Write for Uart {
    fn write_str(&mut self, s: &str) -> fmt::Result {
        for c in s.as_bytes() {
            self.write_byte(*c);
        }
        Ok(())
    }
}

// Safe because it just contains a pointer to device memory, which can be
// accessed from any context.
unsafe impl Send for Uart {}
}

Cargo.toml (you shouldn’t need to change this):

[workspace]

[package]
name = "rtc"
version = "0.1.0"
edition = "2021"
publish = false

[dependencies]
arm-gic = "0.1.0"
bitflags = "2.0.0"
chrono = { version = "0.4.24", default-features = false }
log = "0.4.17"
smccc = "0.1.1"
spin = "0.9.8"

[build-dependencies]
cc = "1.0.73"

build.rs (you shouldn’t need to change this):

// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

use cc::Build;
use std::env;

fn main() {
    #[cfg(target_os = "linux")]
    env::set_var("CROSS_COMPILE", "aarch64-linux-gnu");
    #[cfg(not(target_os = "linux"))]
    env::set_var("CROSS_COMPILE", "aarch64-none-elf");

    Build::new()
        .file("entry.S")
        .file("exceptions.S")
        .file("idmap.S")
        .compile("empty")
}

entry.S (you shouldn’t need to change this):

/*
 * Copyright 2023 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

.macro adr_l, reg:req, sym:req
	adrp \reg, \sym
	add \reg, \reg, :lo12:\sym
.endm

.macro mov_i, reg:req, imm:req
	movz \reg, :abs_g3:\imm
	movk \reg, :abs_g2_nc:\imm
	movk \reg, :abs_g1_nc:\imm
	movk \reg, :abs_g0_nc:\imm
.endm

.set .L_MAIR_DEV_nGnRE,	0x04
.set .L_MAIR_MEM_WBWA,	0xff
.set .Lmairval, .L_MAIR_DEV_nGnRE | (.L_MAIR_MEM_WBWA << 8)

/* 4 KiB granule size for TTBR0_EL1. */
.set .L_TCR_TG0_4KB, 0x0 << 14
/* 4 KiB granule size for TTBR1_EL1. */
.set .L_TCR_TG1_4KB, 0x2 << 30
/* Disable translation table walk for TTBR1_EL1, generating a translation fault instead. */
.set .L_TCR_EPD1, 0x1 << 23
/* Translation table walks for TTBR0_EL1 are inner sharable. */
.set .L_TCR_SH_INNER, 0x3 << 12
/*
 * Translation table walks for TTBR0_EL1 are outer write-back read-allocate write-allocate
 * cacheable.
 */
.set .L_TCR_RGN_OWB, 0x1 << 10
/*
 * Translation table walks for TTBR0_EL1 are inner write-back read-allocate write-allocate
 * cacheable.
 */
.set .L_TCR_RGN_IWB, 0x1 << 8
/* Size offset for TTBR0_EL1 is 2**39 bytes (512 GiB). */
.set .L_TCR_T0SZ_512, 64 - 39
.set .Ltcrval, .L_TCR_TG0_4KB | .L_TCR_TG1_4KB | .L_TCR_EPD1 | .L_TCR_RGN_OWB
.set .Ltcrval, .Ltcrval | .L_TCR_RGN_IWB | .L_TCR_SH_INNER | .L_TCR_T0SZ_512

/* Stage 1 instruction access cacheability is unaffected. */
.set .L_SCTLR_ELx_I, 0x1 << 12
/* SP alignment fault if SP is not aligned to a 16 byte boundary. */
.set .L_SCTLR_ELx_SA, 0x1 << 3
/* Stage 1 data access cacheability is unaffected. */
.set .L_SCTLR_ELx_C, 0x1 << 2
/* EL0 and EL1 stage 1 MMU enabled. */
.set .L_SCTLR_ELx_M, 0x1 << 0
/* Privileged Access Never is unchanged on taking an exception to EL1. */
.set .L_SCTLR_EL1_SPAN, 0x1 << 23
/* SETEND instruction disabled at EL0 in aarch32 mode. */
.set .L_SCTLR_EL1_SED, 0x1 << 8
/* Various IT instructions are disabled at EL0 in aarch32 mode. */
.set .L_SCTLR_EL1_ITD, 0x1 << 7
.set .L_SCTLR_EL1_RES1, (0x1 << 11) | (0x1 << 20) | (0x1 << 22) | (0x1 << 28) | (0x1 << 29)
.set .Lsctlrval, .L_SCTLR_ELx_M | .L_SCTLR_ELx_C | .L_SCTLR_ELx_SA | .L_SCTLR_EL1_ITD | .L_SCTLR_EL1_SED
.set .Lsctlrval, .Lsctlrval | .L_SCTLR_ELx_I | .L_SCTLR_EL1_SPAN | .L_SCTLR_EL1_RES1

/**
 * This is a generic entry point for an image. It carries out the operations required to prepare the
 * loaded image to be run. Specifically, it zeroes the bss section using registers x25 and above,
 * prepares the stack, enables floating point, and sets up the exception vector. It preserves x0-x3
 * for the Rust entry point, as these may contain boot parameters.
 */
.section .init.entry, "ax"
.global entry
entry:
	/* Load and apply the memory management configuration, ready to enable MMU and caches. */
	adrp x30, idmap
	msr ttbr0_el1, x30

	mov_i x30, .Lmairval
	msr mair_el1, x30

	mov_i x30, .Ltcrval
	/* Copy the supported PA range into TCR_EL1.IPS. */
	mrs x29, id_aa64mmfr0_el1
	bfi x30, x29, #32, #4

	msr tcr_el1, x30

	mov_i x30, .Lsctlrval

	/*
	 * Ensure everything before this point has completed, then invalidate any potentially stale
	 * local TLB entries before they start being used.
	 */
	isb
	tlbi vmalle1
	ic iallu
	dsb nsh
	isb

	/*
	 * Configure sctlr_el1 to enable MMU and cache and don't proceed until this has completed.
	 */
	msr sctlr_el1, x30
	isb

	/* Disable trapping floating point access in EL1. */
	mrs x30, cpacr_el1
	orr x30, x30, #(0x3 << 20)
	msr cpacr_el1, x30
	isb

	/* Zero out the bss section. */
	adr_l x29, bss_begin
	adr_l x30, bss_end
0:	cmp x29, x30
	b.hs 1f
	stp xzr, xzr, [x29], #16
	b 0b

1:	/* Prepare the stack. */
	adr_l x30, boot_stack_end
	mov sp, x30

	/* Set up exception vector. */
	adr x30, vector_table_el1
	msr vbar_el1, x30

	/* Call into Rust code. */
	bl main

	/* Loop forever waiting for interrupts. */
2:	wfi
	b 2b

exceptions.S (you shouldn’t need to change this):

/*
 * Copyright 2023 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Saves the volatile registers onto the stack. This currently takes 14
 * instructions, so it can be used in exception handlers with 18 instructions
 * left.
 *
 * On return, x0 and x1 are initialised to elr_el2 and spsr_el2 respectively,
 * which can be used as the first and second arguments of a subsequent call.
 */
.macro save_volatile_to_stack
	/* Reserve stack space and save registers x0-x18, x29 & x30. */
	stp x0, x1, [sp, #-(8 * 24)]!
	stp x2, x3, [sp, #8 * 2]
	stp x4, x5, [sp, #8 * 4]
	stp x6, x7, [sp, #8 * 6]
	stp x8, x9, [sp, #8 * 8]
	stp x10, x11, [sp, #8 * 10]
	stp x12, x13, [sp, #8 * 12]
	stp x14, x15, [sp, #8 * 14]
	stp x16, x17, [sp, #8 * 16]
	str x18, [sp, #8 * 18]
	stp x29, x30, [sp, #8 * 20]

	/*
	 * Save elr_el1 & spsr_el1. This such that we can take nested exception
	 * and still be able to unwind.
	 */
	mrs x0, elr_el1
	mrs x1, spsr_el1
	stp x0, x1, [sp, #8 * 22]
.endm

/**
 * Restores the volatile registers from the stack. This currently takes 14
 * instructions, so it can be used in exception handlers while still leaving 18
 * instructions left; if paired with save_volatile_to_stack, there are 4
 * instructions to spare.
 */
.macro restore_volatile_from_stack
	/* Restore registers x2-x18, x29 & x30. */
	ldp x2, x3, [sp, #8 * 2]
	ldp x4, x5, [sp, #8 * 4]
	ldp x6, x7, [sp, #8 * 6]
	ldp x8, x9, [sp, #8 * 8]
	ldp x10, x11, [sp, #8 * 10]
	ldp x12, x13, [sp, #8 * 12]
	ldp x14, x15, [sp, #8 * 14]
	ldp x16, x17, [sp, #8 * 16]
	ldr x18, [sp, #8 * 18]
	ldp x29, x30, [sp, #8 * 20]

	/* Restore registers elr_el1 & spsr_el1, using x0 & x1 as scratch. */
	ldp x0, x1, [sp, #8 * 22]
	msr elr_el1, x0
	msr spsr_el1, x1

	/* Restore x0 & x1, and release stack space. */
	ldp x0, x1, [sp], #8 * 24
.endm

/**
 * This is a generic handler for exceptions taken at the current EL while using
 * SP0. It behaves similarly to the SPx case by first switching to SPx, doing
 * the work, then switching back to SP0 before returning.
 *
 * Switching to SPx and calling the Rust handler takes 16 instructions. To
 * restore and return we need an additional 16 instructions, so we can implement
 * the whole handler within the allotted 32 instructions.
 */
.macro current_exception_sp0 handler:req
	msr spsel, #1
	save_volatile_to_stack
	bl \handler
	restore_volatile_from_stack
	msr spsel, #0
	eret
.endm

/**
 * This is a generic handler for exceptions taken at the current EL while using
 * SPx. It saves volatile registers, calls the Rust handler, restores volatile
 * registers, then returns.
 *
 * This also works for exceptions taken from EL0, if we don't care about
 * non-volatile registers.
 *
 * Saving state and jumping to the Rust handler takes 15 instructions, and
 * restoring and returning also takes 15 instructions, so we can fit the whole
 * handler in 30 instructions, under the limit of 32.
 */
.macro current_exception_spx handler:req
	save_volatile_to_stack
	bl \handler
	restore_volatile_from_stack
	eret
.endm

.section .text.vector_table_el1, "ax"
.global vector_table_el1
.balign 0x800
vector_table_el1:
sync_cur_sp0:
	current_exception_sp0 sync_exception_current

.balign 0x80
irq_cur_sp0:
	current_exception_sp0 irq_current

.balign 0x80
fiq_cur_sp0:
	current_exception_sp0 fiq_current

.balign 0x80
serr_cur_sp0:
	current_exception_sp0 serr_current

.balign 0x80
sync_cur_spx:
	current_exception_spx sync_exception_current

.balign 0x80
irq_cur_spx:
	current_exception_spx irq_current

.balign 0x80
fiq_cur_spx:
	current_exception_spx fiq_current

.balign 0x80
serr_cur_spx:
	current_exception_spx serr_current

.balign 0x80
sync_lower_64:
	current_exception_spx sync_lower

.balign 0x80
irq_lower_64:
	current_exception_spx irq_lower

.balign 0x80
fiq_lower_64:
	current_exception_spx fiq_lower

.balign 0x80
serr_lower_64:
	current_exception_spx serr_lower

.balign 0x80
sync_lower_32:
	current_exception_spx sync_lower

.balign 0x80
irq_lower_32:
	current_exception_spx irq_lower

.balign 0x80
fiq_lower_32:
	current_exception_spx fiq_lower

.balign 0x80
serr_lower_32:
	current_exception_spx serr_lower

idmap.S (you shouldn’t need to change this):

/*
 * Copyright 2023 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

.set .L_TT_TYPE_BLOCK, 0x1
.set .L_TT_TYPE_PAGE,  0x3
.set .L_TT_TYPE_TABLE, 0x3

/* Access flag. */
.set .L_TT_AF, 0x1 << 10
/* Not global. */
.set .L_TT_NG, 0x1 << 11
.set .L_TT_XN, 0x3 << 53

.set .L_TT_MT_DEV, 0x0 << 2			// MAIR #0 (DEV_nGnRE)
.set .L_TT_MT_MEM, (0x1 << 2) | (0x3 << 8)	// MAIR #1 (MEM_WBWA), inner shareable

.set .L_BLOCK_DEV, .L_TT_TYPE_BLOCK | .L_TT_MT_DEV | .L_TT_AF | .L_TT_XN
.set .L_BLOCK_MEM, .L_TT_TYPE_BLOCK | .L_TT_MT_MEM | .L_TT_AF | .L_TT_NG

.section ".rodata.idmap", "a", %progbits
.global idmap
.align 12
idmap:
	/* level 1 */
	.quad		.L_BLOCK_DEV | 0x0		    // 1 GiB of device mappings
	.quad		.L_BLOCK_MEM | 0x40000000	// 1 GiB of DRAM
	.fill		254, 8, 0x0			// 254 GiB of unmapped VA space
	.quad		.L_BLOCK_DEV | 0x4000000000 // 1 GiB of device mappings
	.fill		255, 8, 0x0			// 255 GiB of remaining VA space

image.ld (you shouldn’t need to change this):

/*
 * Copyright 2023 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/*
 * Code will start running at this symbol which is placed at the start of the
 * image.
 */
ENTRY(entry)

MEMORY
{
	image : ORIGIN = 0x40080000, LENGTH = 2M
}

SECTIONS
{
	/*
	 * Collect together the code.
	 */
	.init : ALIGN(4096) {
		text_begin = .;
		*(.init.entry)
		*(.init.*)
	} >image
	.text : {
		*(.text.*)
	} >image
	text_end = .;

	/*
	 * Collect together read-only data.
	 */
	.rodata : ALIGN(4096) {
		rodata_begin = .;
		*(.rodata.*)
	} >image
	.got : {
		*(.got)
	} >image
	rodata_end = .;

	/*
	 * Collect together the read-write data including .bss at the end which
	 * will be zero'd by the entry code.
	 */
	.data : ALIGN(4096) {
		data_begin = .;
		*(.data.*)
		/*
		 * The entry point code assumes that .data is a multiple of 32
		 * bytes long.
		 */
		. = ALIGN(32);
		data_end = .;
	} >image

	/* Everything beyond this point will not be included in the binary. */
	bin_end = .;

	/* The entry point code assumes that .bss is 16-byte aligned. */
	.bss : ALIGN(16)  {
		bss_begin = .;
		*(.bss.*)
		*(COMMON)
		. = ALIGN(16);
		bss_end = .;
	} >image

	.stack (NOLOAD) : ALIGN(4096) {
		boot_stack_begin = .;
		. += 40 * 4096;
		. = ALIGN(4096);
		boot_stack_end = .;
	} >image

	. = ALIGN(4K);
	PROVIDE(dma_region = .);

	/*
	 * Remove unused sections from the image.
	 */
	/DISCARD/ : {
		/* The image loads itself so doesn't need these sections. */
		*(.gnu.hash)
		*(.hash)
		*(.interp)
		*(.eh_frame_hdr)
		*(.eh_frame)
		*(.note.gnu.build-id)
	}
}

Makefile (you shouldn’t need to change this):

# Copyright 2023 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

UNAME := $(shell uname -s)
ifeq ($(UNAME),Linux)
	TARGET = aarch64-linux-gnu
else
	TARGET = aarch64-none-elf
endif
OBJCOPY = $(TARGET)-objcopy

.PHONY: build qemu_minimal qemu qemu_logger

all: rtc.bin

build:
	cargo build

rtc.bin: build
	$(OBJCOPY) -O binary target/aarch64-unknown-none/debug/rtc $@

qemu: rtc.bin
	qemu-system-aarch64 -machine virt,gic-version=3 -cpu max -serial mon:stdio -display none -kernel $< -s

clean:
	cargo clean
	rm -f *.bin

.cargo/config.toml (you shouldn’t need to change this):

[build]
target = "aarch64-unknown-none"
rustflags = ["-C", "link-arg=-Timage.ld"]

Run the code in QEMU with make qemu.

Welcome to Concurrency in Rust

Rust tem suporte total para concorrência usando threads do SO com mutexes e channels (canais).

O sistema de tipos do Rust desempenha um papel importante na conversão de muitos erros de concorrência em erros de tempo de compilação. Isso geralmente é chamado de concorrência sem medo, pois você pode confiar no compilador para garantir a exatidão no tempo de execução.

Threads

Threads em Rust funcionam de maneira semelhante às threads em outras linguagens:

use std::thread;
use std::time::Duration;

fn main() {
    thread::spawn(|| {
        for i in 1..10 {
            println!("Count in thread: {i}!");
            thread::sleep(Duration::from_millis(5));
        }
    });

    for i in 1..5 {
        println!("Main thread: {i}");
        thread::sleep(Duration::from_millis(5));
    }
}

• Threads são todas “daemon threads”, o thread principal não espera por elas.
• “Panics” em threads são independentes uns dos outros.
  • “Panics” podem carregar um payload (carga útil), que pode ser descompactado com downcast_ref.

Threads com Escopo

Threads normais não podem emprestar de seu ambiente:

use std::thread;

fn foo() {
    let s = String::from("Olá");
    thread::spawn(|| {
        println!("Length: {}", s.len());
    });
}

fn main() {
    foo();
}

No entanto, você pode usar uma thread com escopo para isso:

use std::thread;

fn main() {
    let s = String::from("Olá");

    thread::scope(|scope| {
        scope.spawn(|| {
            println!("Length: {}", s.len());
        });
    });
}

Canais (channels)

Os channels (canais) em Rust têm duas partes: um Sender<T> e um Receiver<T>. As duas partes estão conectadas através do channel, mas você só vê os end-points.

use std::sync::mpsc;
use std::thread;

fn main() {
    let (tx, rx) = mpsc::channel();

    tx.send(10).unwrap();
    tx.send(20).unwrap();

    println!("Received: {:?}", rx.recv());
    println!("Received: {:?}", rx.recv());

    let tx2 = tx.clone();
    tx2.send(30).unwrap();
    println!("Received: {:?}", rx.recv());
}

Canais Ilimitados

Você obtém um canal ilimitado e assíncrono com mpsc::channel():

use std::sync::mpsc;
use std::thread;
use std::time::Duration;

fn main() {
    let (tx, rx) = mpsc::channel();

    thread::spawn(move || {
        let thread_id = thread::current().id();
        for i in 1..10 {
            tx.send(format!("Message {i}")).unwrap();
            println!("{thread_id:?}: sent Message {i}");
        }
        println!("{thread_id:?}: done");
    });
    thread::sleep(Duration::from_millis(100));

    for msg in rx.iter() {
        println!("Main: got {msg}");
    }
}

Canais Delimitados

With bounded (synchronous) channels, send can block the current thread:

use std::sync::mpsc;
use std::thread;
use std::time::Duration;

fn main() {
    let (tx, rx) = mpsc::sync_channel(3);

    thread::spawn(move || {
        let thread_id = thread::current().id();
        for i in 1..10 {
            tx.send(format!("Message {i}")).unwrap();
            println!("{thread_id:?}: sent Message {i}");
        }
        println!("{thread_id:?}: done");
    });
    thread::sleep(Duration::from_millis(100));

    for msg in rx.iter() {
        println!("Main: got {msg}");
    }
}

Send e Sync

Como o Rust sabe proibir o acesso compartilhado entre threads? A resposta está em duas características:

• Send: um tipo T é Send se for seguro mover um T entre threads
• Sync: um tipo T é Sync se for seguro mover um &T entre threads

Send e Sync são unsafe traits. O compilador os derivará automaticamente para seus tipos desde que contenham apenas os tipos Send e Sync. Você também pode implementá-los manualmente quando souber que são válidos.

Send

Um tipo T é Send se for seguro mover um valor T para outro thread.

O efeito de mover a propriedade (ownership) para outro thread é que os destructors serão executados nessa thread. Então a questão é: quando você pode alocar um valor em um thread e desalocá-lo em outro?

Sync

Um tipo T é Sync se for seguro acessar um valor T de várias threads ao mesmo tempo.

Mais precisamente, a definição é:

T é Sync se e somente se &T é Send

Exemplos

Send + Sync

A maioria dos tipos que você encontra são Send + Sync:

• i8, f32, bool, char, &str, …
• (T1, T2), [T; N], &[T], struct { x: T }, …
• String, Option<T>, Vec<T>, Box<T>, …
• Arc<T>: Explicitamente thread-safe via contagem de referência atômica.
• Mutex<T>: Explicitamente thread-safe via bloqueio interno.
• AtomicBool, AtomicU8, …: Usa instruções atômicas especiais.

Os tipos genéricos são tipicamente Send + Sync quando os parâmetros de tipo são Send + Sync.

Send + !Sync

Esses tipos podem ser movidos para outras threads, mas não são seguros para threads. Normalmente por causa da mutabilidade interior:

• mpsc::Sender<T>
• mpsc::Receiver<T>
• Cell<T>
• RefCell<T>

!Send + Sync

Esses tipos são thread-safe, mas não podem ser movidos para outro thread:

• MutexGuard<T>: Usa primitivas a nível de sistema operacional que devem ser desalocadas no thread que as criou.

!Send + !Sync

Esses tipos não são thread-safe e não podem ser movidos para outros threads:

• Rc<T>: cada Rc<T> tem uma referência a um RcBox<T>, que contém uma contagem de referência não atômica.
• *const T, *mut T: Rust assume que ponteiros brutos podem ter considerações de especiais de concorrência.

Estado Compartilhado

Rust usa o sistema de tipos para impor a sincronização de dados compartilhados. Isso é feito principalmente através de dois tipos:

• Arc<T>, referência atômica contada T: manipula o compartilhamento entre threads e toma o cuidado de desalocar T quando a última referência é descartada,
• Mutex<T>: garante acesso mutuamente exclusivo ao valor T.

Arc

Arc<T> allows shared read-only access via Arc::clone:

use std::thread;
use std::sync::Arc;

fn main() {
    let v = Arc::new(vec![10, 20, 30]);
    let mut handles = Vec::new();
    for _ in 1..5 {
        let v = Arc::clone(&v);
        handles.push(thread::spawn(move || {
            let thread_id = thread::current().id();
            println!("{thread_id:?}: {v:?}");
        }));
    }

    handles.into_iter().for_each(|h| h.join().unwrap());
    println!("v: {v:?}");
}

Mutex

Mutex<T> garante exclusão mútua e permite acesso mutável a T por trás de uma interface somente leitura:

use std::sync::Mutex;

fn main() {
    let v = Mutex::new(vec![10, 20, 30]);
    println!("v: {:?}", v.lock().unwrap());

    {
        let mut guard = v.lock().unwrap();
        guard.push(40);
    }

    println!("v: {:?}", v.lock().unwrap());
}

Observe como temos uma implementação impl<T: Send> Sync for Mutex<T> encoberta.

Exemplo

Vamos ver Arc e Mutex em ação:

use std::thread;
// use std::sync::{Arc, Mutex};

fn main() {
    let v = vec![10, 20, 30];
    let handle = thread::spawn(|| {
        v.push(10);
    });
    v.push(1000);

    handle.join().unwrap();
    println!("v: {v:?}");
}

use std::sync::{Arc, Mutex};
use std::thread;

fn main() {
    let v = Arc::new(Mutex::new(vec![10, 20, 30]));

    let v2 = Arc::clone(&v);
    let handle = thread::spawn(move || {
        let mut v2 = v2.lock().unwrap();
        v2.push(10);
    });

    {
        let mut v = v.lock().unwrap();
        v.push(1000);
    }

    handle.join().unwrap();

    println!("v: {v:?}");
}

Exercícios

Vamos praticar nossas novas habilidades de concorrência com:

• Dining philosophers: a classic problem in concurrency.

• Multi-threaded link checker: a larger project where you’ll use Cargo to download dependencies and then check links in parallel.

Filósofos Jantando

O problema dos filósofos jantando é um problema clássico em concorrência:

Cinco filósofos jantam juntos na mesma mesa. Cada folósofo tem seu próprio lugar à mesa. Há um garfo entre cada prato. O prato servido é uma espécie de espaguete que se come com dois garfos. Cada filósofo pode somente pensar ou comer, alternadamente. Além disso, um filósofo só pode comer seu espaguete quando ele têm garfo esquerdo e direito. Assim, dois garfos só estarão disponíveis quando seus dois vizinhos mais próximos estiverem pensando, não comendo. Depois de um filósofo individual termina de comer, ele abaixa os dois garfos.

You will need a local Cargo installation for this exercise. Copy the code below to a file called src/main.rs, fill out the blanks, and test that cargo run does not deadlock:

use std::sync::{mpsc, Arc, Mutex};
use std::thread;
use std::time::Duration;

struct Fork;

struct Philosopher {
    name: String,
    // left_fork: ...
    // right_fork: ...
    // thoughts: ...
}

impl Philosopher {
    fn think(&self) {
        self.thoughts
            .send(format!("Eureka! {} has a new idea!", &self.name))
            .unwrap();
    }

    fn eat(&self) {
        // Pick up forks...
        println!("{} is eating...", &self.name);
        thread::sleep(Duration::from_millis(10));
    }
}

static PHILOSOPHERS: &[&str] =
    &["Socrates", "Plato", "Aristotle", "Thales", "Pythagoras"];

fn main() {
    // Create forks

    // Create philosophers

    // Make each of them think and eat 100 times

    // Output their thoughts
}

You can use the following Cargo.toml:

[package]
name = "dining-philosophers"
version = "0.1.0"
edition = "2021"

Verificador de Links Multi-Threads

Vamos usar nosso novo conhecimento para criar um verificador de links multi-threads. Comece em uma página da web e verifique se os links na página são válidos. Verifique recursivamente outras páginas no mesmo domínio e continue fazendo isso até que todas as páginas tenham sido validadas.

Para isso, você precisará de um cliente HTTP como reqwest. Crie um novo Project com o Cargo e adicione reqwest como uma dependência:

cargo new link-checker
cd link-checker
cargo add --features blocking,rustls-tls reqwest

Se cargo add falhar com error: no such subcommand, edite o arquivo Cargo.toml à mão. Adicione as dependências listadas abaixo.

Você também precisará de uma maneira de encontrar links. Podemos usar scraper para isso:

cargo add scraper

Por fim, precisaremos de alguma forma de lidar com os erros. Usamos thiserror para isso:

cargo add thiserror

As chamadas cargo add irão atualizar o arquivo Cargo.toml para ficar assim:

[package]
name = "link-checker"
version = "0.1.0"
edition = "2021"
publish = false

[dependencies]
reqwest = { version = "0.11.12", features = ["blocking", "rustls-tls"] }
scraper = "0.13.0"
thiserror = "1.0.37"

Agora você pode baixar a página inicial. Tente com um pequeno site como https://www.google.org/.

Seu arquivo src/main.rs deve se parecer com isto:

use reqwest::{blocking::Client, Url};
use scraper::{Html, Selector};
use thiserror::Error;

#[derive(Error, Debug)]
enum Error {
    #[error("request error: {0}")]
    ReqwestError(#[from] reqwest::Error),
    #[error("bad http response: {0}")]
    BadResponse(String),
}

#[derive(Debug)]
struct CrawlCommand {
    url: Url,
    extract_links: bool,
}

fn visit_page(client: &Client, command: &CrawlCommand) -> Result<Vec<Url>, Error> {
    println!("Checking {:#}", command.url);
    let response = client.get(command.url.clone()).send()?;
    if !response.status().is_success() {
        return Err(Error::BadResponse(response.status().to_string()));
    }

    let mut link_urls = Vec::new();
    if !command.extract_links {
        return Ok(link_urls);
    }

    let base_url = response.url().to_owned();
    let body_text = response.text()?;
    let document = Html::parse_document(&body_text);

    let selector = Selector::parse("a").unwrap();
    let href_values = document
        .select(&selector)
        .filter_map(|element| element.value().attr("href"));
    for href in href_values {
        match base_url.join(href) {
            Ok(link_url) => {
                link_urls.push(link_url);
            }
            Err(err) => {
                println!("On {base_url:#}: ignored unparsable {href:?}: {err}");
            }
        }
    }
    Ok(link_urls)
}

fn main() {
    let client = Client::new();
    let start_url = Url::parse("https://www.google.org").unwrap();
    let crawl_command = CrawlCommand{ url: start_url, extract_links: true };
    match visit_page(&client, &crawl_command) {
        Ok(links) => println!("Links: {links:#?}"),
        Err(err) => println!("Could not extract links: {err:#}"),
    }
}

Execute o código em src/main.rs com

cargo run

Tarefas

• Use threads para verificar os links em paralelo: envie as URLs a serem verificadas para um channel e deixe alguns threads verificarem as URLs em paralelo.
• Estenda isso para extrair recursivamente links de todas as páginas no domínio www.google.org. Coloque um limite máximo de 100 páginas ou menos para que você não acabe sendo bloqueado pelo site.

Async Rust

“Async” is a concurrency model where multiple tasks are executed concurrently by executing each task until it would block, then switching to another task that is ready to make progress. The model allows running a larger number of tasks on a limited number of threads. This is because the per-task overhead is typically very low and operating systems provide primitives for efficiently identifying I/O that is able to proceed.

Rust’s asynchronous operation is based on “futures”, which represent work that may be completed in the future. Futures are “polled” until they signal that they are complete.

Futures are polled by an async runtime, and several different runtimes are available.

Comparisons

• Python has a similar model in its asyncio. However, its Future type is callback-based, and not polled. Async Python programs require a “loop”, similar to a runtime in Rust.

• JavaScript’s Promise is similar, but again callback-based. The language runtime implements the event loop, so many of the details of Promise resolution are hidden.

async/await

At a high level, async Rust code looks very much like “normal” sequential code:

use futures::executor::block_on;

async fn count_to(count: i32) {
    for i in 1..=count {
        println!("Count is: {i}!");
    }
}

async fn async_main(count: i32) {
    count_to(count).await;
}

fn main() {
    block_on(async_main(10));
}

Closures

Future is a trait, implemented by objects that represent an operation that may not be complete yet. A future can be polled, and poll returns a Poll.

#![allow(unused)]
fn main() {
use std::pin::Pin;
use std::task::Context;

pub trait Future {
    type Output;
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}

pub enum Poll<T> {
    Ready(T),
    Pending,
}
}

An async function returns an impl Future. It’s also possible (but uncommon) to implement Future for your own types. For example, the JoinHandle returned from tokio::spawn implements Future to allow joining to it.

The .await keyword, applied to a Future, causes the current async function to pause until that Future is ready, and then evaluates to its output.

Tempos de Execução

A runtime provides support for performing operations asynchronously (a reactor) and is responsible for executing futures (an executor). Rust does not have a “built-in” runtime, but several options are available:

• Tokio: performant, with a well-developed ecosystem of functionality like Hyper for HTTP or Tonic for gRPC.
• async-std: aims to be a “std for async”, and includes a basic runtime in async::task.
• smol: simple and lightweight

Several larger applications have their own runtimes. For example, Fuchsia already has one.

Tokio

Tokio provides:

• A multi-threaded runtime for executing asynchronous code.
• An asynchronous version of the standard library.
• A large ecosystem of libraries.

use tokio::time;

async fn count_to(count: i32) {
    for i in 1..=count {
        println!("Count in task: {i}!");
        time::sleep(time::Duration::from_millis(5)).await;
    }
}

#[tokio::main]
async fn main() {
    tokio::spawn(count_to(10));

    for i in 1..5 {
        println!("Main task: {i}");
        time::sleep(time::Duration::from_millis(5)).await;
    }
}

Tarefas

Rust has a task system, which is a form of lightweight threading.

A task has a single top-level future which the executor polls to make progress. That future may have one or more nested futures that its poll method polls, corresponding loosely to a call stack. Concurrency within a task is possible by polling multiple child futures, such as racing a timer and an I/O operation.

use tokio::io::{self, AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;

#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:6142").await?;
	println!("listening on port 6142");

    loop {
        let (mut socket, addr) = listener.accept().await?;

        println!("connection from {addr:?}");

        tokio::spawn(async move {
            if let Err(e) = socket.write_all(b"Who are you?\n").await {
                println!("socket error: {e:?}");
                return;
            }

            let mut buf = vec![0; 1024];
            let reply = match socket.read(&mut buf).await {
                Ok(n) => {
                    let name = std::str::from_utf8(&buf[..n]).unwrap().trim();
                    format!("Thanks for dialing in, {name}!\n")
                }
                Err(e) => {
                    println!("socket error: {e:?}");
                    return;
                }
            };

            if let Err(e) = socket.write_all(reply.as_bytes()).await {
                println!("socket error: {e:?}");
            }
        });
    }
}

Canais Assíncronos

Several crates have support for asynchronous channels. For instance tokio:

use tokio::sync::mpsc::{self, Receiver};

async fn ping_handler(mut input: Receiver<()>) {
    let mut count: usize = 0;

    while let Some(_) = input.recv().await {
        count += 1;
        println!("Received {count} pings so far.");
    }

    println!("ping_handler complete");
}

#[tokio::main]
async fn main() {
    let (sender, receiver) = mpsc::channel(32);
    let ping_handler_task = tokio::spawn(ping_handler(receiver));
    for i in 0..10 {
        sender.send(()).await.expect("Failed to send ping.");
        println!("Sent {} pings so far.", i + 1);
    }

    drop(sender);
    ping_handler_task.await.expect("Something went wrong in ping handler task.");
}

Futures Control Flow

Futures can be combined together to produce concurrent compute flow graphs. We have already seen tasks, that function as independent threads of execution.

• Join
• Select

Join

A join operation waits until all of a set of futures are ready, and returns a collection of their results. This is similar to Promise.all in JavaScript or asyncio.gather in Python.

use anyhow::Result;
use futures::future;
use reqwest;
use std::collections::HashMap;

async fn size_of_page(url: &str) -> Result<usize> {
    let resp = reqwest::get(url).await?;
    Ok(resp.text().await?.len())
}

#[tokio::main]
async fn main() {
    let urls: [&str; 4] = [
        "https://google.com",
        "https://httpbin.org/ip",
        "https://play.rust-lang.org/",
        "BAD_URL",
    ];
    let futures_iter = urls.into_iter().map(size_of_page);
    let results = future::join_all(futures_iter).await;
    let page_sizes_dict: HashMap<&str, Result<usize>> =
        urls.into_iter().zip(results.into_iter()).collect();
    println!("{:?}", page_sizes_dict);
}

Select

A select operation waits until any of a set of futures is ready, and responds to that future’s result. In JavaScript, this is similar to Promise.race. In Python, it compares to asyncio.wait(task_set, return_when=asyncio.FIRST_COMPLETED).

Similar to a match statement, the body of select! has a number of arms, each of the form pattern = future => statement. When the future is ready, the statement is executed with the variables in pattern bound to the future’s result.

use tokio::sync::mpsc::{self, Receiver};
use tokio::time::{sleep, Duration};

#[derive(Debug, PartialEq)]
enum Animal {
    Cat { name: String },
    Dog { name: String },
}

async fn first_animal_to_finish_race(
    mut cat_rcv: Receiver<String>,
    mut dog_rcv: Receiver<String>,
) -> Option<Animal> {
    tokio::select! {
        cat_name = cat_rcv.recv() => Some(Animal::Cat { name: cat_name? }),
        dog_name = dog_rcv.recv() => Some(Animal::Dog { name: dog_name? })
    }
}

#[tokio::main]
async fn main() {
    let (cat_sender, cat_receiver) = mpsc::channel(32);
    let (dog_sender, dog_receiver) = mpsc::channel(32);
    tokio::spawn(async move {
        sleep(Duration::from_millis(500)).await;
        cat_sender
            .send(String::from("Felix"))
            .await
            .expect("Failed to send cat.");
    });
    tokio::spawn(async move {
        sleep(Duration::from_millis(50)).await;
        dog_sender
            .send(String::from("Rex"))
            .await
            .expect("Failed to send dog.");
    });

    let winner = first_animal_to_finish_race(cat_receiver, dog_receiver)
        .await
        .expect("Failed to receive winner");

    println!("Winner is {winner:?}");
}

Pitfalls of async/await

Async / await provides convenient and efficient abstraction for concurrent asynchronous programming. However, the async/await model in Rust also comes with its share of pitfalls and footguns. We illustrate some of them in this chapter:

• Blocking the Executor
• Pin
• Async Traits
• Cancellation

Blocking the executor

Most async runtimes only allow IO tasks to run concurrently. This means that CPU blocking tasks will block the executor and prevent other tasks from being executed. An easy workaround is to use async equivalent methods where possible.

use futures::future::join_all;
use std::time::Instant;

async fn sleep_ms(start: &Instant, id: u64, duration_ms: u64) {
    std::thread::sleep(std::time::Duration::from_millis(duration_ms));
    println!(
        "future {id} slept for {duration_ms}ms, finished after {}ms",
        start.elapsed().as_millis()
    );
}

#[tokio::main(flavor = "current_thread")]
async fn main() {
    let start = Instant::now();
    let sleep_futures = (1..=10).map(|t| sleep_ms(&start, t, t * 10));
    join_all(sleep_futures).await;
}

Pin

When you await a future, all local variables (that would ordinarily be stored on a stack frame) are instead stored in the Future for the current async block. If your future has pointers to data on the stack, those pointers might get invalidated. This is unsafe.

Therefore, you must guarantee that the addresses your future points to don’t change. That is why we need to pin futures. Using the same future repeatedly in a select! often leads to issues with pinned values.

use tokio::sync::{mpsc, oneshot};
use tokio::task::spawn;
use tokio::time::{sleep, Duration};

// A work item. In this case, just sleep for the given time and respond
// with a message on the `respond_on` channel.
#[derive(Debug)]
struct Work {
    input: u32,
    respond_on: oneshot::Sender<u32>,
}

// A worker which listens for work on a queue and performs it.
async fn worker(mut work_queue: mpsc::Receiver<Work>) {
    let mut iterations = 0;
    loop {
        tokio::select! {
            Some(work) = work_queue.recv() => {
                sleep(Duration::from_millis(10)).await; // Pretend to work.
                work.respond_on
                    .send(work.input * 1000)
                    .expect("failed to send response");
                iterations += 1;
            }
            // TODO: report number of iterations every 100ms
        }
    }
}

// A requester which requests work and waits for it to complete.
async fn do_work(work_queue: &mpsc::Sender<Work>, input: u32) -> u32 {
    let (tx, rx) = oneshot::channel();
    work_queue
        .send(Work {
            input,
            respond_on: tx,
        })
        .await
        .expect("failed to send on work queue");
    rx.await.expect("failed waiting for response")
}

#[tokio::main]
async fn main() {
    let (tx, rx) = mpsc::channel(10);
    spawn(worker(rx));
    for i in 0..100 {
        let resp = do_work(&tx, i).await;
        println!("work result for iteration {i}: {resp}");
    }
}

Traits (Características)

Async methods in traits are not yet supported in the stable channel (An experimental feature exists in nightly and should be stabilized in the mid term.)

The crate async_trait provides a workaround through a macro:

use async_trait::async_trait;
use std::time::Instant;
use tokio::time::{sleep, Duration};

#[async_trait]
trait Sleeper {
    async fn sleep(&self);
}

struct FixedSleeper {
    sleep_ms: u64,
}

#[async_trait]
impl Sleeper for FixedSleeper {
    async fn sleep(&self) {
        sleep(Duration::from_millis(self.sleep_ms)).await;
    }
}

async fn run_all_sleepers_multiple_times(sleepers: Vec<Box<dyn Sleeper>>, n_times: usize) {
    for _ in 0..n_times {
        println!("running all sleepers..");
        for sleeper in &sleepers {
            let start = Instant::now();
            sleeper.sleep().await;
            println!("slept for {}ms", start.elapsed().as_millis());
        }
    }
}

#[tokio::main]
async fn main() {
    let sleepers: Vec<Box<dyn Sleeper>> = vec![
        Box::new(FixedSleeper { sleep_ms: 50 }),
        Box::new(FixedSleeper { sleep_ms: 100 }),
    ];
    run_all_sleepers_multiple_times(sleepers, 5).await;
}

Cancelar

Dropping a future implies it can never be polled again. This is called cancellation and it can occur at any await point. Care is needed to ensure the system works correctly even when futures are cancelled. For example, it shouldn’t deadlock or lose data.

use std::io::{self, ErrorKind};
use std::time::Duration;
use tokio::io::{AsyncReadExt, AsyncWriteExt, DuplexStream};

struct LinesReader {
    stream: DuplexStream,
}

impl LinesReader {
    fn new(stream: DuplexStream) -> Self {
        Self { stream }
    }

    async fn next(&mut self) -> io::Result<Option<String>> {
        let mut bytes = Vec::new();
        let mut buf = [0];
        while self.stream.read(&mut buf[..]).await? != 0 {
            bytes.push(buf[0]);
            if buf[0] == b'\n' {
                break;
            }
        }
        if bytes.is_empty() {
            return Ok(None)
        }
        let s = String::from_utf8(bytes)
            .map_err(|_| io::Error::new(ErrorKind::InvalidData, "not UTF-8"))?;
        Ok(Some(s))
    }
}

async fn slow_copy(source: String, mut dest: DuplexStream) -> std::io::Result<()> {
    for b in source.bytes() {
        dest.write_u8(b).await?;
        tokio::time::sleep(Duration::from_millis(10)).await
    }
    Ok(())
}

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let (client, server) = tokio::io::duplex(5);
    let handle = tokio::spawn(slow_copy("hi\nthere\n".to_owned(), client));

    let mut lines = LinesReader::new(server);
    let mut interval = tokio::time::interval(Duration::from_millis(60));
    loop {
        tokio::select! {
            _ = interval.tick() => println!("tick!"),
            line = lines.next() => if let Some(l) = line? {
                print!("{}", l)
            } else {
                break
            },
        }
    }
    handle.await.unwrap()?;
    Ok(())
}

Exercícios

To practice your Async Rust skills, we have again two exercises for you:

• Dining philosophers: we already saw this problem in the morning. This time you are going to implement it with Async Rust.

• A Broadcast Chat Application: this is a larger project that allows you experiment with more advanced Async Rust features.

Dining Philosophers - Async

See dining philosophers for a description of the problem.

As before, you will need a local Cargo installation for this exercise. Copy the code below to a file called src/main.rs, fill out the blanks, and test that cargo run does not deadlock:

use std::sync::Arc;
use tokio::time;
use tokio::sync::mpsc::{self, Sender};
use tokio::sync::Mutex;

struct Fork;

struct Philosopher {
    name: String,
    // left_fork: ...
    // right_fork: ...
    // thoughts: ...
}

impl Philosopher {
    async fn think(&self) {
        self.thoughts
            .send(format!("Eureka! {} has a new idea!", &self.name)).await
            .unwrap();
    }

    async fn eat(&self) {
        // Pick up forks...
        println!("{} is eating...", &self.name);
        time::sleep(time::Duration::from_millis(5)).await;
    }
}

static PHILOSOPHERS: &[&str] =
    &["Socrates", "Plato", "Aristotle", "Thales", "Pythagoras"];

#[tokio::main]
async fn main() {
    // Create forks

    // Create philosophers

    // Make them think and eat

    // Output their thoughts
}

Since this time you are using Async Rust, you’ll need a tokio dependency. You can use the following Cargo.toml:

[package]
name = "dining-philosophers-async-dine"
version = "0.1.0"
edition = "2021"

[dependencies]
tokio = {version = "1.26.0", features = ["sync", "time", "macros", "rt-multi-thread"]}

Also note that this time you have to use the Mutex and the mpsc module from the tokio crate.

Broadcast Chat Application

In this exercise, we want to use our new knowledge to implement a broadcast chat application. We have a chat server that the clients connect to and publish their messages. The client reads user messages from the standard input, and sends them to the server. The chat server broadcasts each message that it receives to all the clients.

For this, we use a broadcast channel on the server, and tokio_websockets for the communication between the client and the server.

Create a new Cargo project and add the following dependencies:

Cargo.toml:

[package]
name = "chat-async"
version = "0.1.0"
edition = "2021"

[dependencies]
futures-util = "0.3.28"
http = "0.2.9"
tokio = { version = "1.28.1", features = ["full"] }
tokio-websockets = "0.3.2"

The required APIs

You are going to need the following functions from tokio and tokio_websockets. Spend a few minutes to familiarize yourself with the API.

• WebsocketStream::next(): for asynchronously reading messages from a Websocket Stream.
• SinkExt::send() implemented by WebsocketStream: for asynchronously sending messages on a Websocket Stream.
• Lines::next_line(): for asynchronously reading user messages from the standard input.
• Sender::subscribe(): for subscribing to a broadcast channel.

Two binaries

Normally in a Cargo project, you can have only one binary, and one src/main.rs file. In this project, we need two binaries. One for the client, and one for the server. You could potentially make them two separate Cargo projects, but we are going to put them in a single Cargo project with two binaries. For this to work, the client and the server code should go under src/bin (see the documentation).

Copy the following server and client code into src/bin/server.rs and src/bin/client.rs, respectively. Your task is to complete these files as described below.

src/bin/server.rs:

use futures_util::sink::SinkExt;
use std::error::Error;
use std::net::SocketAddr;
use tokio::net::{TcpListener, TcpStream};
use tokio::sync::broadcast::{channel, Sender};
use tokio_websockets::{Message, ServerBuilder, WebsocketStream};

async fn handle_connection(
    addr: SocketAddr,
    mut ws_stream: WebsocketStream<TcpStream>,
    bcast_tx: Sender<String>,
) -> Result<(), Box<dyn Error + Send + Sync>> {

    // TODO: For a hint, see the description of the task below.

}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
    let (bcast_tx, _) = channel(16);

    let listener = TcpListener::bind("127.0.0.1:2000").await?;
    println!("listening on port 2000");

    loop {
        let (socket, addr) = listener.accept().await?;
        println!("New connection from {addr:?}");
        let bcast_tx = bcast_tx.clone();
        tokio::spawn(async move {
            // Wrap the raw TCP stream into a websocket.
            let ws_stream = ServerBuilder::new().accept(socket).await?;

            handle_connection(addr, ws_stream, bcast_tx).await
        });
    }
}

src/bin/client.rs:

use futures_util::SinkExt;
use http::Uri;
use tokio::io::{AsyncBufReadExt, BufReader};
use tokio_websockets::{ClientBuilder, Message};

#[tokio::main]
async fn main() -> Result<(), tokio_websockets::Error> {
    let mut ws_stream = ClientBuilder::from_uri(Uri::from_static("ws://127.0.0.1:2000"))
        .connect()
        .await?;

    let stdin = tokio::io::stdin();
    let mut stdin = BufReader::new(stdin).lines();


    // TODO: For a hint, see the description of the task below.

}

Running the binaries

Run the server with:

cargo run --bin server

and the client with:

cargo run --bin client

Tarefas

• Implement the handle_connection function in src/bin/server.rs.
  • Hint: Use tokio::select! for concurrently performing two tasks in a continuous loop. One task receives messages from the client and broadcasts them. The other sends messages received by the server to the client.
• Complete the main function in src/bin/client.rs.
  • Hint: As before, use tokio::select! in a continuous loop for concurrently performing two tasks: (1) reading user messages from standard input and sending them to the server, and (2) receiving messages from the server, and displaying them for the user.
• Optional: Once you are done, change the code to broadcast messages to all clients, but the sender of the message.

Obrigado!

Obrigado por fazer o Comprehensive Rust 🦀! Esperamos que tenha gostado e que tenha sido útil.

Nós nos divertimos muito montando o curso. O curso não é perfeito, portanto, se você identificou algum erro ou tem ideias para melhorias, entre em entre em contato conosco em GitHub. Nós adoraríamos ouvir você.

Outros recursos de Rust

A comunidade Rust tem abundância de recursos gratuitos e de alta qualidade on-line.

Documentação Oficial

O projeto Rust hospeda muitos recursos. Estes cobrem Rust em geral:

• A Linguagem de Programação Rust: o livro gratuito canônico sobre Rust. Abrange o idioma em detalhes e inclui alguns projetos para as pessoas construírem.
• Rust By Example: abrange a sintaxe de Rust por meio de uma série de exemplos que mostram diferentes construções. As vezes inclui pequenos exercícios onde você é solicitado a expandir o código dos exemplos.
• Rust Standard Library: documentação completa da biblioteca padrão para Rust.
• The Rust Reference: um livro incompleto que descreve a gramática Rust e o modelo de memória.

Mais guias especializados hospedados no site oficial do Rust:

• O Rustonomicon: cobre Rust inseguro, incluindo trabalhar com ponteiros brutos e fazer interface com outras linguagens (FFI).
• Programação assíncrona em Rust: abrange o novo modelo de programação assíncrona que foi introduzido após o Rust Book ser escrito.
• The Embedded Rust Book: uma introdução ao uso do Rust em dispositivos embarcados sem um sistema operacional.

Material de aprendizagem não oficial

Uma pequena seleção de outros guias e tutoriais para Rust:

• Learn Rust the Dangerous Way: covers Rust from the perspective of low-level C programmers.
• Rust for Embedded C Programmers: covers Rust from the perspective of developers who write firmware in C.
• Rust for professionals: covers the syntax of Rust using side-by-side comparisons with other languages such as C, C++, Java, JavaScript, and Python.
• Rust on Exercism: 100+ exercises to help you learn Rust.
• Ferrous Teaching Material: a series of small presentations covering both basic and advanced part of the Rust language. Other topics such as WebAssembly, and async/await are also covered.
• Beginner’s Series to Rust and Take your first steps with Rust: two Rust guides aimed at new developers. The first is a set of 35 videos and the second is a set of 11 modules which covers Rust syntax and basic constructs.
• Learn Rust With Entirely Too Many Linked Lists: in-depth exploration of Rust’s memory management rules, through implementing a few different types of list structures.

Consulte o Little Book of Rust Books para ainda mais livros Rust.

Créditos

O material aqui se baseia em muitas fontes excelentes de documentação do Rust. Consulte a página em outros recursos para obter uma lista completa de recursos úteis .

The material of Comprehensive Rust is licensed under the terms of the Apache 2.0 license, please see LICENSE for details.

Rust by Example