Go Eficiente

Nota: este documento foi escrito para o lançamento do Go em 2009 e não é mais atualizado ativamente. Ele continua sendo um bom guia para usar a linguagem central, mas não cobre mudanças significativas na linguagem (genéricos), no ecossistema (módulos) ou nas bibliotecas adicionadas desde então. Veja a issue 28782 para contexto. Para a lista completa de mudanças, veja as notas de lançamento.

Introdução

Go é uma linguagem de programação de código aberto que prioriza simplicidade, confiabilidade e eficiência, projetada especificamente para facilitar a construção de software em escala. Embora tome emprestadas ideias de linguagens existentes, ela tem propriedades incomuns que tornam os programas Go eficientes diferentes em essência dos programas escritos em suas parentes. Uma tradução direta de um programa C++ ou Java para Go dificilmente produz um resultado satisfatório—programas Java são escritos em Java, não em Go. Por outro lado, pensar no problema a partir de uma perspectiva Go pode produzir um programa bem-sucedido, mas bem diferente. Em outras palavras, para escrever Go bem, é importante entender suas propriedades e idiomas. Também é importante conhecer as convenções estabelecidas para programar em Go, como nomes, formatação, construção de programas e assim por diante, para que os programas que você escreve sejam fáceis de entender para outros programadores Go.

Este documento dá dicas para escrever código Go claro e idiomático. Ele complementa a especificação da linguagem, o Tour of Go e Como escrever código Go, todos os quais você deve ler primeiro.

Exemplos

Os fontes dos pacotes Go servem não apenas como a biblioteca central, mas também como exemplos de como usar a linguagem. Além disso, muitos dos pacotes contêm exemplos executáveis, funcionais e autocontidos que você pode rodar diretamente no site go.dev, como este (se necessário, clique na palavra "Example" para abri-lo). Se você tiver dúvida sobre como abordar um problema ou como algo poderia ser implementado, a documentação, o código e os exemplos na biblioteca podem oferecer respostas, ideias e contexto.

Formatação

Questões de formatação são as mais controversas, mas as de menor consequência. As pessoas se adaptam a diferentes estilos de formatação, mas é melhor que não precisem, e gasta-se menos tempo com o assunto se todos seguirem o mesmo estilo. O problema é como chegar a essa Utopia sem um longo guia de estilo prescritivo.

Em Go, adotamos uma abordagem incomum e deixamos a máquina cuidar da maioria das questões de formatação. O programa gofmt (também disponível como go fmt, que opera no nível do pacote em vez do nível do arquivo de código-fonte) lê um programa Go e emite o código-fonte em um estilo padrão de indentação e alinhamento vertical, preservando e, se necessário, reformatando os comentários. Se você quiser saber como lidar com alguma nova situação de layout, execute gofmt; se a resposta não parecer certa, reorganize o programa (ou abra um bug sobre gofmt), mas não contorne o problema.

Como exemplo, não há necessidade de gastar tempo alinhando os comentários dos campos de uma struct. Gofmt faz isso por você. Dada a declaração

type T struct {
    name string // name of the object
    value int // its value
}

gofmt vai alinhar as colunas:

type T struct {
    name    string // name of the object
    value   int    // its value
}

Todo o código da biblioteca padrão foi formatado com gofmt.

Restam alguns detalhes de formatação. Muito brevemente:

Indentação
Usamos tabs para indentar e o gofmt os emite por padrão. Use espaços somente se for necessário.
Tamanho da linha
Go não tem limite de tamanho de linha. Não se preocupe em estourar um cartão perfurado. Se uma linha parecer longa demais, quebre-a e indente com um tab extra.
Parênteses
Go precisa de menos parênteses que C e Java: estruturas de controle (if, for, switch) não têm parênteses na sua sintaxe. Além disso, a hierarquia de precedência de operadores é mais curta e mais clara, então
x<<8 + y<<16
significa o que o espaçamento sugere, ao contrário das outras linguagens.

Comentários

Go oferece comentários de bloco no estilo C, /* */, e comentários de linha no estilo C++, //. Comentários de linha são o padrão; comentários de bloco aparecem principalmente como comentários de pacote, mas são úteis dentro de uma expressão ou para desativar trechos grandes de código.

Comentários que aparecem antes de declarações de nível superior, sem linhas em branco entre eles, são considerados como documentando a própria declaração. Esses “comentários de documentação” são a principal documentação de um pacote ou comando Go. Para saber mais sobre comentários de documentação, veja “Comentários de documentação em Go”.

Nomes

Nomes são tão importantes em Go quanto em qualquer outra linguagem. Eles têm até efeito semântico: a visibilidade de um nome fora de um pacote é determinada por se o seu primeiro caractere é maiúsculo. Vale a pena, portanto, dedicar um pouco de tempo às convenções de nomenclatura em programas Go.

Nomes de pacotes

Quando um pacote é importado, o nome do pacote se torna um acessador para o conteúdo. Depois de

import "bytes"

o pacote que importa pode usar bytes.Buffer. Ajuda se todos que usam o pacote puderem usar o mesmo nome para se referir a seu conteúdo, o que implica que o nome do pacote deve ser bom: curto, conciso, sugestivo. Por convenção, os pacotes recebem nomes em letras minúsculas, com uma única palavra; não deve haver necessidade de sublinhados ou mixedCaps. Prefira a brevidade, já que todos que usarem o seu pacote vão digitar esse nome. E não se preocupe com colisões a priori. O nome do pacote é apenas o nome padrão para importações; ele não precisa ser único em todo o código-fonte, e, no raro caso de colisão, o pacote que importa pode escolher outro nome para usar localmente. De qualquer forma, a confusão é rara, porque o nome do arquivo na importação determina exatamente qual pacote está sendo usado.

Outra convenção é que o nome do pacote é o nome base de seu diretório de código-fonte; o pacote em src/encoding/base64 é importado como "encoding/base64", mas tem o nome base64, não encoding_base64 e não encodingBase64.

Quem importa um pacote vai usar o nome para se referir ao seu conteúdo, então os nomes exportados no pacote podem aproveitar esse fato para evitar repetição. (Não use a notação import ., que pode simplificar testes que precisam rodar fora do pacote que estão testando, mas que, de outro modo, deve ser evitada.) Por exemplo, o tipo de leitor com buffer no pacote bufio se chama Reader, não BufReader, porque os usuários o veem como bufio.Reader, que é um nome claro e conciso. Além disso, como entidades importadas são sempre acessadas com o nome do pacote, bufio.Reader não conflita com io.Reader. Da mesma forma, a função que cria novas instâncias de ring.Ring—que é a definição de um construtor em Go—normalmente seria chamada NewRing, mas, como Ring é o único tipo exportado pelo pacote, e como o pacote se chama ring, ela se chama apenas New, que quem usa o pacote enxerga como ring.New. Use a estrutura do pacote para ajudar a escolher bons nomes.

Outro exemplo curto é once.Do; once.Do(setup) lê bem e não seria melhorado ao escrever once.DoOrWaitUntilDone(setup). Nomes longos não tornam as coisas mais legíveis automaticamente. Um comentário de documentação útil costuma ser mais valioso que um nome extra longo.

Getters

Go não oferece suporte automático a getters e setters. Não há nada de errado em você mesmo criar getters e setters, e muitas vezes isso é apropriado, mas não é idiomático nem necessário colocar Get no nome do getter. Se você tiver um campo chamado owner (minúsculo, não exportado), o método getter deve se chamar Owner (maiúsculo, exportado), não GetOwner. O uso de nomes com inicial maiúscula para exportação oferece o mecanismo para distinguir o campo do método. Uma função setter, se necessária, provavelmente se chamará SetOwner. Na prática, os dois nomes ficam bem:

owner := obj.Owner()
if owner != user {
    obj.SetOwner(user)
}

Nomes de interfaces

Por convenção, interfaces com um único método recebem o nome do método com o sufixo -er ou uma modificação semelhante para formar um substantivo de agente: Reader, Writer, Formatter, CloseNotifier etc.

Existem vários nomes assim, e vale a pena respeitá-los e às funções que eles capturam. Read, Write, Close, Flush, String e assim por diante têm assinaturas e significados canônicos. Para evitar confusão, não dê ao seu método um desses nomes, a menos que ele tenha a mesma assinatura e o mesmo significado. Inversamente, se o seu tipo implementar um método com o mesmo significado de um método de um tipo conhecido, dê a ele o mesmo nome e assinatura; chame o seu método conversor de string de String, não ToString.

MixedCaps

Por fim, a convenção em Go é usar MixedCaps ou mixedCaps, em vez de sublinhados, para escrever nomes com várias palavras.

Ponto e vírgula

Assim como em C, a gramática formal de Go usa ponto e vírgula para terminar instruções, mas, diferentemente de C, esses pontos e vírgulas não aparecem no código-fonte. Em vez disso, o analisador léxico usa uma regra simples para inserir pontos e vírgulas automaticamente enquanto lê o texto, então o texto de entrada fica quase sempre sem eles.

A regra é esta. Se o último token antes de uma quebra de linha for um identificador (o que inclui palavras como int e float64), um literal básico, como um número ou uma constante de string, ou um dos tokens

break continue fallthrough return ++ -- ) }

o analisador léxico sempre insere um ponto e vírgula depois do token. Isso pode ser resumido assim: “se a quebra de linha vier depois de um token que poderia terminar uma instrução, insira um ponto e vírgula”.

Um ponto e vírgula também pode ser omitido imediatamente antes de uma chave de fechamento, então uma instrução como

    go func() { for { dst <- <-src } }()

não precisa de pontos e vírgulas. Programas Go idiomáticos têm pontos e vírgulas apenas em lugares como as cláusulas de um laço for, para separar os elementos de inicialização, condição e continuação. Eles também são necessários para separar várias instruções em uma mesma linha, caso você escreva código assim.

Uma consequência das regras de inserção de ponto e vírgula é que você não pode colocar a chave de abertura de uma estrutura de controle (if, for, switch, ou select) na linha seguinte. Se fizer isso, um ponto e vírgula será inserido antes da chave, o que pode causar efeitos indesejados. Escreva assim

if i < f() {
    g()
}

e não assim

if i < f()  // wrong!
{           // wrong!
    g()
}

Estruturas de controle

As estruturas de controle de Go são parecidas com as de C, mas diferem em aspectos importantes. Não há laço do nem while, apenas um for um pouco mais generalizado; switch é mais flexível; if e switch aceitam uma instrução de inicialização opcional, como a do for; as instruções break e continue aceitam um rótulo opcional para identificar o que interromper ou continuar; e há novas estruturas de controle, incluindo o switch de tipos e um multiplexador de comunicação de múltiplas vias, o select. A sintaxe também é um pouco diferente: não há parênteses, e os blocos devem sempre ser delimitados por chaves.

If

Em Go, um if simples fica assim:

if x > 0 {
    return y
}

As chaves obrigatórias incentivam a escrita de instruções if simples em várias linhas. De qualquer forma, esse é um bom estilo, especialmente quando o bloco contém uma instrução de controle, como um return ou break.

Como if e switch aceitam uma instrução de inicialização, é comum ver uma delas usada para configurar uma variável local.

if err := file.Chmod(0664); err != nil {
    log.Print(err)
    return err
}

Nas bibliotecas de Go, você vai notar que quando uma instrução if não segue para a próxima instrução, ou seja, o bloco termina em break, continue, goto ou return, o else desnecessário é omitido.

f, err := os.Open(name)
if err != nil {
    return err
}
codeUsing(f)

Este é um exemplo de uma situação comum em que o código precisa se proteger contra uma sequência de condições de erro. O código fica legível se o fluxo de sucesso descer pela página, eliminando os casos de erro à medida que surgem. Como os casos de erro tendem a terminar em instruções return, o código resultante não precisa de instruções else.

f, err := os.Open(name)
if err != nil {
    return err
}
d, err := f.Stat()
if err != nil {
    f.Close()
    return err
}
codeUsing(f, d)

Redeclaração e reatribuição

Um parêntese: o último exemplo da seção anterior demonstra um detalhe de como a forma de declaração curta := funciona. A declaração que chama os.Open lê-se assim:

f, err := os.Open(name)

Essa instrução declara duas variáveis, f e err. Algumas linhas depois, a chamada a f.Stat lê-se assim:

d, err := f.Stat()

que parece declarar d e err. Note, porém, que err aparece nas duas instruções. Essa duplicação é válida: err é declarada pela primeira instrução, mas só é reatribuída na segunda. Isso significa que a chamada a f.Stat usa a variável err já declarada acima e apenas lhe dá um novo valor.

Em uma declaração :=, uma variável v pode aparecer mesmo que já tenha sido declarada, desde que:

Essa propriedade incomum é puro pragmatismo, tornando fácil usar um único valor err, por exemplo, em uma longa cadeia if-else. Você vai vê-la usada com frequência.

§ Vale notar aqui que, em Go, o escopo dos parâmetros e dos valores de retorno de uma função é o mesmo do corpo da função, mesmo que eles apareçam lexicalmente fora das chaves que delimitam o corpo.

For

O laço for de Go é parecido com o de C, mas não é igual. Ele unifica for e while, e não existe do-while. Há três formas, e apenas uma delas tem ponto e vírgula.

// Like a C for
for init; condition; post { }

// Like a C while
for condition { }

// Like a C for(;;)
for { }

Declarações curtas facilitam declarar a variável de índice bem no laço.

sum := 0
for i := 0; i < 10; i++ {
    sum += i
}

Se você estiver percorrendo um array, slice, string ou map, ou lendo de um canal, uma cláusula range pode cuidar do laço.

for key, value := range oldMap {
    newMap[key] = value
}

Se você só precisar do primeiro item do range (a chave ou o índice), omita o segundo:

for key := range m {
    if key.expired() {
        delete(m, key)
    }
}

Se você só precisar do segundo item do range (o valor), use o identificador em branco, um sublinhado, para descartar o primeiro:

sum := 0
for _, value := range array {
    sum += value
}

O identificador em branco tem muitos usos, como descrito em uma seção posterior.

Para strings, o range faz mais trabalho por você, separando cada ponto de código Unicode ao interpretar o UTF-8. Codificações erradas consomem um byte e produzem a runa de substituição U+FFFD. (O nome rune, com o tipo embutido associado, é a terminologia de Go para um único ponto de código Unicode. Veja a especificação da linguagem para detalhes.) O laço

for pos, char := range "日本\x80語" { // \x80 is an illegal UTF-8 encoding
    fmt.Printf("character %#U starts at byte position %d\n", char, pos)
}

imprime

character U+65E5 '日' starts at byte position 0
character U+672C '本' starts at byte position 3
character U+FFFD '�' starts at byte position 6
character U+8A9E '語' starts at byte position 7

Por fim, Go não tem operador vírgula, e ++ e -- são instruções, não expressões. Assim, se você quiser executar várias variáveis em um for, deve usar atribuição paralela (embora isso exclua ++ e --).

// Reverse a
for i, j := 0, len(a)-1; i < j; i, j = i+1, j-1 {
    a[i], a[j] = a[j], a[i]
}

Switch

O switch de Go é mais geral que o de C. As expressões não precisam ser constantes nem mesmo inteiros, os casos são avaliados de cima para baixo até encontrar uma correspondência, e, se o switch não tiver expressão, ele compara com true. Por isso é possível—e idiomático—escrever uma cadeia de if-else-if-else como um switch.

func unhex(c byte) byte {
    switch {
    case '0' <= c && c <= '9':
        return c - '0'
    case 'a' <= c && c <= 'f':
        return c - 'a' + 10
    case 'A' <= c && c <= 'F':
        return c - 'A' + 10
    }
    return 0
}

Não há continuação automática para o próximo caso (fall through), mas os casos podem ser apresentados em listas separadas por vírgula.

func shouldEscape(c byte) bool {
    switch c {
    case ' ', '?', '&', '=', '#', '+', '%':
        return true
    }
    return false
}

Embora sejam bem menos comuns em Go do que em outras linguagens parecidas com C, as instruções break podem ser usadas para encerrar um switch mais cedo. Às vezes, porém, é preciso sair de um laço externo, e não do switch; em Go, isso se faz colocando um rótulo no laço e "quebrando" até esse rótulo. Este exemplo mostra os dois usos.

Loop:
    for n := 0; n < len(src); n += size {
        switch {
        case src[n] < sizeOne:
            if validateOnly {
                break
            }
            size = 1
            update(src[n])

        case src[n] < sizeTwo:
            if n+1 >= len(src) {
                err = errShortInput
                break Loop
            }
            if validateOnly {
                break
            }
            size = 2
            update(src[n] + src[n+1]<<shift)
        }
    }

Claro, a instrução continue também aceita um rótulo opcional, mas ela se aplica somente a laços.

Para encerrar esta seção, aqui está uma rotina de comparação para slices de bytes que usa duas instruções switch:

// Compare returns an integer comparing the two byte slices,
// lexicographically.
// The result will be 0 if a == b, -1 if a < b, and +1 if a > b
func Compare(a, b []byte) int {
    for i := 0; i < len(a) && i < len(b); i++ {
        switch {
        case a[i] > b[i]:
            return 1
        case a[i] < b[i]:
            return -1
        }
    }
    switch {
    case len(a) > len(b):
        return 1
    case len(a) < len(b):
        return -1
    }
    return 0
}

Switch de tipo

Um switch também pode ser usado para descobrir o tipo dinâmico de uma variável de interface. Esse switch de tipo usa a sintaxe de uma asserção de tipo, com a palavra-chave type dentro dos parênteses. Se o switch declarar uma variável na expressão, a variável terá o tipo correspondente em cada cláusula. Também é idiomático reutilizar o nome nesses casos, declarando na prática uma nova variável com o mesmo nome, mas com um tipo diferente em cada caso.

var t interface{}
t = functionOfSomeType()
switch t := t.(type) {
default:
    fmt.Printf("unexpected type %T\n", t)     // %T prints whatever type t has
case bool:
    fmt.Printf("boolean %t\n", t)             // t has type bool
case int:
    fmt.Printf("integer %d\n", t)             // t has type int
case *bool:
    fmt.Printf("pointer to boolean %t\n", *t) // t has type *bool
case *int:
    fmt.Printf("pointer to integer %d\n", *t) // t has type *int
}

Funções

Múltiplos valores de retorno

Uma das características incomuns de Go é que funções e métodos podem retornar múltiplos valores. Essa forma pode ser usada para melhorar alguns idiomas desajeitados dos programas em C: retornos de erro misturados ao próprio valor de retorno, como -1 para EOF, e a modificação de um argumento passado por endereço.

Em C, um erro de escrita é sinalizado por uma contagem negativa, com o código de erro guardado em uma posição volátil. Em Go, Write pode retornar uma contagem e um erro: “Sim, você escreveu alguns bytes, mas não todos, porque encheu o dispositivo”. A assinatura do método Write em arquivos do pacote os é:

func (file *File) Write(b []byte) (n int, err error)

e, como diz a documentação, ele retorna o número de bytes escritos e um error não nulo quando n != len(b). Este é um estilo comum; veja a seção sobre tratamento de erros para mais exemplos.

Uma abordagem semelhante dispensa a necessidade de passar um ponteiro para um valor de retorno para simular um parâmetro por referência. Aqui está uma função simplificada para pegar um número de uma posição em um slice de bytes, retornando o número e a próxima posição.

func nextInt(b []byte, i int) (int, int) {
    for ; i < len(b) && !isDigit(b[i]); i++ {
    }
    x := 0
    for ; i < len(b) && isDigit(b[i]); i++ {
        x = x*10 + int(b[i]) - '0'
    }
    return x, i
}

Você poderia usá-la para percorrer os números em um slice de entrada b assim:

    for i := 0; i < len(b); {
        x, i = nextInt(b, i)
        fmt.Println(x)
    }

Parâmetros de resultado nomeados

Os "parâmetros" de retorno ou de resultado de uma função Go podem receber nomes e ser usados como variáveis comuns, assim como os parâmetros de entrada. Quando nomeados, são inicializados com os valores zero de seus tipos quando a função começa; se a função executar uma instrução return sem argumentos, os valores atuais dos parâmetros de resultado são usados como valores retornados.

Os nomes não são obrigatórios, mas podem tornar o código mais curto e mais claro: eles são documentação. Se nomearmos os resultados de nextInt, fica óbvio qual int retornado é qual.

func nextInt(b []byte, pos int) (value, nextPos int) {

Como os resultados nomeados são inicializados e vinculados a um return sem argumentos, eles podem simplificar e também esclarecer. Aqui está uma versão de io.ReadFull que os usa bem:

func ReadFull(r Reader, buf []byte) (n int, err error) {
    for len(buf) > 0 && err == nil {
        var nr int
        nr, err = r.Read(buf)
        n += nr
        buf = buf[nr:]
    }
    return
}

Defer

A instrução defer de Go agenda uma chamada de função (a função adiada) para ser executada imediatamente antes de a função que executa o defer retornar. É uma forma incomum, mas eficaz, de lidar com situações como recursos que precisam ser liberados independentemente do caminho que a função toma para retornar. Os exemplos canônicos são destravar um mutex ou fechar um arquivo.

// Contents returns the file's contents as a string.
func Contents(filename string) (string, error) {
    f, err := os.Open(filename)
    if err != nil {
        return "", err
    }
    defer f.Close()  // f.Close will run when we're finished.

    var result []byte
    buf := make([]byte, 100)
    for {
        n, err := f.Read(buf[0:])
        result = append(result, buf[0:n]...) // append is discussed later.
        if err != nil {
            if err == io.EOF {
                break
            }
            return "", err  // f will be closed if we return here.
        }
    }
    return string(result), nil // f will be closed if we return here.
}

Adiar a chamada de uma função como Close tem duas vantagens. Primeiro, ela garante que você nunca vai esquecer de fechar o arquivo, um erro fácil de cometer se você editar a função depois para incluir um novo caminho de retorno. Segundo, faz com que o fechamento fique perto da abertura, o que é muito mais claro do que colocá-lo no final da função.

Os argumentos da função adiada (que incluem o receptor, se a função for um método) são avaliados quando o defer é executado, não quando a chamada é executada. Além de evitar preocupações com variáveis mudando de valor enquanto a função executa, isso significa que um único ponto de chamada com defer pode adiar várias execuções de função. Aqui está um exemplo bobo.

for i := 0; i < 5; i++ {
    defer fmt.Printf("%d ", i)
}

Funções adiadas são executadas em ordem LIFO (último a entrar, primeiro a sair), então este código fará 4 3 2 1 0 ser impresso quando a função retornar. Um exemplo mais plausível é uma forma simples de rastrear a execução de funções pelo programa. Poderíamos escrever algumas rotinas simples de rastreamento assim:

func trace(s string)   { fmt.Println("entering:", s) }
func untrace(s string) { fmt.Println("leaving:", s) }

// Use them like this:
func a() {
    trace("a")
    defer untrace("a")
    // do something....
}

Podemos fazer melhor aproveitando o fato de que os argumentos das funções adiadas são avaliados quando o defer é executado. A rotina de rastreamento pode preparar o argumento para a rotina de encerramento do rastreamento. Este exemplo:

func trace(s string) string {
    fmt.Println("entering:", s)
    return s
}

func un(s string) {
    fmt.Println("leaving:", s)
}

func a() {
    defer un(trace("a"))
    fmt.Println("in a")
}

func b() {
    defer un(trace("b"))
    fmt.Println("in b")
    a()
}

func main() {
    b()
}

imprime

entering: b
in b
entering: a
in a
leaving: a
leaving: b

Para programadores acostumados ao gerenciamento de recursos por bloco de outras linguagens, o defer pode parecer estranho, mas suas aplicações mais interessantes e poderosas vêm justamente do fato de ele não ser baseado em blocos, e sim em funções. Na seção sobre panic e recover veremos outro exemplo de suas possibilidades.

Dados

Alocação com new

Go tem duas primitivas de alocação, as funções embutidas new e make. Elas fazem coisas diferentes e se aplicam a tipos diferentes, o que pode ser confuso, mas as regras são simples. Vamos falar de new primeiro. É uma função embutida que aloca memória, mas, diferentemente das homônimas em outras linguagens, ela não inicializa a memória, apenas a zera. Ou seja, new(T) aloca armazenamento zerado para uma nova variável do tipo T e retorna o seu endereço, um valor do tipo *T. Na terminologia de Go, ela retorna um ponteiro para um valor zero recém-alocado do tipo T.

A partir do Go 1.26, new também aceita uma expressão (de valor) como argumento, que especifica o valor inicial da variável. Por exemplo, new(int64(300)) aloca uma nova variável do tipo int64, inicializada com 300, e retorna o seu endereço.

Como a memória retornada por new é zerada, é útil planejar, ao projetar suas estruturas de dados, que o valor zero de cada tipo possa ser usado sem inicialização adicional. Isso significa que quem usa a estrutura de dados pode criar uma com new e começar a trabalhar logo. Por exemplo, a documentação de bytes.Buffer diz que "o valor zero de Buffer é um buffer vazio pronto para uso." De forma semelhante, sync.Mutex não tem um construtor explícito nem um método Init. Em vez disso, o valor zero de um sync.Mutex é definido como um mutex destravado.

A propriedade de que o valor zero é útil funciona de forma transitiva. Considere esta declaração de tipo.

type SyncedBuffer struct {
    lock    sync.Mutex
    buffer  bytes.Buffer
}

Valores do tipo SyncedBuffer também ficam prontos para uso imediatamente após a alocação ou apenas a declaração. No próximo trecho, tanto p quanto v vão funcionar corretamente sem mais preparação.

p := new(SyncedBuffer)  // type *SyncedBuffer
var v SyncedBuffer      // type  SyncedBuffer

Construtores e literais compostos

Às vezes o valor zero não basta, e um construtor de inicialização é necessário, como neste exemplo derivado do pacote os.

func NewFile(fd int, name string) *File {
    if fd < 0 {
        return nil
    }
    f := new(File)
    f.fd = fd
    f.name = name
    f.dirinfo = nil
    f.nepipe = 0
    return f
}

Há muito código repetitivo aí. Podemos simplificá-lo usando um literal composto, que é uma expressão que cria uma nova instância sempre que é avaliada.

func NewFile(fd int, name string) *File {
    if fd < 0 {
        return nil
    }
    f := File{fd, name, nil, 0}
    return &f
}

Observe que, diferentemente de C, é perfeitamente válido retornar o endereço de uma variável local; o armazenamento associado à variável sobrevive depois que a função retorna. Na verdade, tomar o endereço de um literal composto aloca uma nova instância sempre que ele é avaliado, então podemos combinar essas duas últimas linhas.

    return &File{fd, name, nil, 0}

Os campos de um literal composto são dispostos em ordem e precisam estar todos presentes. No entanto, ao rotular os elementos explicitamente como pares campo:valor, os inicializadores podem aparecer em qualquer ordem, e os que faltarem ficam com seus respectivos valores zero. Assim, poderíamos escrever

    return &File{fd: fd, name: name}

Como caso-limite, se um literal composto não tiver nenhum campo, ele cria um valor zero para o tipo. As expressões new(File) e &File{} são equivalentes.

Literais compostos também podem ser criados para arrays, slices e maps, com os rótulos dos campos sendo índices ou chaves de map, conforme o caso. Nestes exemplos, as inicializações funcionam independentemente dos valores de Enone, Eio e Einval, desde que sejam distintos.

a := [...]string   {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
s := []string      {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
m := map[int]string{Enone: "no error", Eio: "Eio", Einval: "invalid argument"}

Alocação com make

Voltando à alocação. A função embutida make(T, args) tem uma finalidade diferente de new(T). Ela cria apenas slices, maps e canais, e retorna um valor inicializado (não zerado) do tipo T (não *T). A razão da distinção é que esses três tipos representam, por baixo dos panos, referências a estruturas de dados que precisam ser inicializadas antes do uso. Um slice, por exemplo, é um descritor de três itens contendo um ponteiro para os dados (dentro de um array), o comprimento e a capacidade; enquanto esses itens não forem inicializados, o slice é nil. Para slices, maps e canais, make inicializa a estrutura de dados interna e prepara o valor para uso. Por exemplo,

make([]int, 10, 100)

aloca um array de 100 ints e então cria uma estrutura de slice com comprimento 10 e capacidade 100 apontando para os primeiros 10 elementos do array. (Ao criar um slice, a capacidade pode ser omitida; veja a seção sobre slices para mais informações.) Já new([]int) retorna um ponteiro para uma estrutura de slice recém-alocada e zerada, ou seja, um ponteiro para um valor de slice nil.

Estes exemplos ilustram a diferença entre new e make.

var p *[]int = new([]int)       // allocates slice structure; *p == nil; rarely useful
var v  []int = make([]int, 100) // the slice v now refers to a new array of 100 ints

// Unnecessarily complex:
var p *[]int = new([]int)
*p = make([]int, 100, 100)

// Idiomatic:
v := make([]int, 100)

Lembre-se de que make se aplica apenas a maps, slices e canais e não retorna um ponteiro. Para obter um ponteiro explícito, aloque com new ou tome o endereço de uma variável explicitamente.

Arrays

Arrays são úteis ao planejar o layout detalhado da memória e às vezes podem ajudar a evitar alocações, mas, principalmente, são um bloco de construção para slices, o assunto da próxima seção. Para preparar a base desse tópico, seguem algumas palavras sobre arrays.

Há diferenças importantes entre a forma como arrays funcionam em Go e em C. Em Go,

A propriedade de valor pode ser útil, mas também custosa; se você quiser o comportamento e a eficiência de C, pode passar um ponteiro para o array.

func Sum(a *[3]float64) (sum float64) {
    for _, v := range *a {
        sum += v
    }
    return
}

array := [...]float64{7.0, 8.5, 9.1}
x := Sum(&array)  // Note the explicit address-of operator

Mesmo assim, esse estilo também não é Go idiomático. Use slices.

Slices

Slices envolvem arrays para oferecer uma interface mais geral, poderosa e conveniente para sequências de dados. Exceto para itens com dimensão explícita, como matrizes de transformação, a maior parte da programação com arrays em Go é feita com slices, e não com arrays simples.

Slices guardam referências a um array subjacente, e, se você atribuir um slice a outro, ambos se referem ao mesmo array. Se uma função recebe um argumento slice, as mudanças que ela fizer nos elementos do slice ficarão visíveis para quem chamou, de forma análoga a passar um ponteiro para o array subjacente. Por isso, uma função Read pode aceitar um argumento slice em vez de um ponteiro e uma contagem; o comprimento dentro do slice define um limite máximo de quantos dados ler. Esta é a assinatura do método Read do tipo File do pacote os:

func (f *File) Read(buf []byte) (n int, err error)

O método retorna o número de bytes lidos e um valor de erro, se houver. Para ler nos primeiros 32 bytes de um buffer maior buf, fatie (aqui usado como verbo) o buffer.

    n, err := f.Read(buf[0:32])

Esse fatiamento é comum e eficiente. Na verdade, deixando a eficiência de lado por enquanto, o trecho a seguir também leria os primeiros 32 bytes do buffer.

    var n int
    var err error
    for i := 0; i < 32; i++ {
        nbytes, e := f.Read(buf[i:i+1])  // Read one byte.
        n += nbytes
        if nbytes == 0 || e != nil {
            err = e
            break
        }
    }

O comprimento de um slice pode ser alterado desde que ele continue cabendo nos limites do array subjacente; basta atribuí-lo a um slice de si mesmo. A capacidade de um slice, acessível pela função embutida cap, informa o comprimento máximo que o slice pode assumir. Aqui está uma função para anexar dados a um slice. Se os dados excederem a capacidade, o slice é realocado. O slice resultante é retornado. A função usa o fato de que len e cap são válidos quando aplicados ao slice nil, e retornam 0.

func Append(slice, data []byte) []byte {
    l := len(slice)
    if l + len(data) > cap(slice) {  // reallocate
        // Allocate double what's needed, for future growth.
        newSlice := make([]byte, (l+len(data))*2)
        // The copy function is predeclared and works for any slice type.
        copy(newSlice, slice)
        slice = newSlice
    }
    slice = slice[0:l+len(data)]
    copy(slice[l:], data)
    return slice
}

Precisamos retornar o slice depois porque, embora Append possa modificar os elementos de slice, o próprio slice (a estrutura de dados em tempo de execução que guarda o ponteiro, o comprimento e a capacidade) é passado por valor.

A ideia de anexar a um slice é tão útil que foi incorporada à função embutida append. Para entender o projeto dessa função, porém, precisamos de um pouco mais de informação, então voltaremos a ela depois.

Slices bidimensionais

Os arrays e slices de Go são unidimensionais. Para criar o equivalente a um array ou slice 2D, é necessário definir um array de arrays ou um slice de slices, assim:

type Transform [3][3]float64  // A 3x3 array, really an array of arrays.
type LinesOfText [][]byte     // A slice of byte slices.

Como slices têm comprimento variável, é possível que cada slice interno tenha um comprimento diferente. Isso pode ser uma situação comum, como no nosso exemplo LinesOfText: cada linha tem um comprimento independente.

text := LinesOfText{
    []byte("Now is the time"),
    []byte("for all good gophers"),
    []byte("to bring some fun to the party."),
}

Às vezes é necessário alocar um slice 2D, situação que pode surgir ao processar linhas de varredura de pixels, por exemplo. Há duas formas de fazer isso. Uma é alocar cada slice independentemente; a outra é alocar um único array e apontar os slices individuais para ele. Qual usar depende da sua aplicação. Se os slices puderem crescer ou encolher, devem ser alocados independentemente para não sobrescrever a linha seguinte; se não, pode ser mais eficiente construir o objeto com uma única alocação. Para referência, seguem esboços dos dois métodos. Primeiro, uma linha por vez:

// Allocate the top-level slice.
picture := make([][]uint8, YSize) // One row per unit of y.
// Loop over the rows, allocating the slice for each row.
for i := range picture {
    picture[i] = make([]uint8, XSize)
}

E agora como uma única alocação, fatiada em linhas:

// Allocate the top-level slice, the same as before.
picture := make([][]uint8, YSize) // One row per unit of y.
// Allocate one large slice to hold all the pixels.
pixels := make([]uint8, XSize*YSize) // Has type []uint8 even though picture is [][]uint8.
// Loop over the rows, slicing each row from the front of the remaining pixels slice.
for i := range picture {
    picture[i], pixels = pixels[:XSize], pixels[XSize:]
}

Maps

Maps são uma estrutura de dados embutida, conveniente e poderosa, que associa valores de um tipo (a chave) a valores de outro tipo (o elemento ou valor). A chave pode ser de qualquer tipo para o qual o operador de igualdade esteja definido, como inteiros, números de ponto flutuante e complexos, strings, ponteiros, interfaces (desde que o tipo dinâmico suporte igualdade), structs e arrays. Slices não podem ser usados como chaves de map, porque a igualdade não é definida para eles. Assim como os slices, os maps guardam referências a uma estrutura de dados subjacente. Se você passar um map para uma função que altera o conteúdo do map, as mudanças ficarão visíveis para quem chamou.

Maps podem ser construídos com a sintaxe usual de literais compostos com pares chave-valor separados por dois-pontos, então é fácil construí-los durante a inicialização.

var timeZone = map[string]int{
    "UTC":  0*60*60,
    "EST": -5*60*60,
    "CST": -6*60*60,
    "MST": -7*60*60,
    "PST": -8*60*60,
}

Atribuir e buscar valores de map tem a mesma sintaxe de fazer o mesmo com arrays e slices, exceto que o índice não precisa ser um inteiro.

offset := timeZone["EST"]

Uma tentativa de buscar um valor de map com uma chave que não está presente no map retorna o valor zero do tipo das entradas do map. Por exemplo, se o map contiver inteiros, consultar uma chave inexistente retorna 0. Um conjunto (set) pode ser implementado como um map com tipo de valor bool. Atribua true à entrada do map para colocar o valor no conjunto e, em seguida, teste-o com uma indexação simples.

attended := map[string]bool{
    "Ann": true,
    "Joe": true,
    ...
}

if attended[person] { // will be false if person is not in the map
    fmt.Println(person, "was at the meeting")
}

Às vezes você precisa distinguir uma entrada ausente de um valor zero. Existe uma entrada para "UTC" ou esse 0 está ali porque ela não está no map? Você pode distinguir isso com uma forma de atribuição múltipla.

var seconds int
var ok bool
seconds, ok = timeZone[tz]

Por razões óbvias, isso é chamado de idioma “vírgula ok”. Neste exemplo, se tz estiver presente, seconds será definido adequadamente e ok será verdadeiro; se não, seconds será definido como zero e ok será falso. Aqui está uma função que junta tudo com um bom relatório de erro:

func offset(tz string) int {
    if seconds, ok := timeZone[tz]; ok {
        return seconds
    }
    log.Println("unknown time zone:", tz)
    return 0
}

Para testar a presença no map sem se preocupar com o valor em si, você pode usar o identificador em branco (_) no lugar da variável usual do valor.

_, present := timeZone[tz]

Para remover uma entrada de map, use a função embutida delete, cujos argumentos são o map e a chave a ser removida. É seguro fazer isso mesmo que a chave já esteja ausente do map.

delete(timeZone, "PDT")  // Now on Standard Time

Impressão

A impressão formatada em Go usa um estilo semelhante ao da família printf de C, mas é mais rica e mais geral. As funções ficam no pacote fmt e têm nomes com inicial maiúscula: fmt.Printf, fmt.Fprintf, fmt.Sprintf e assim por diante. As funções de string (Sprintf etc.) retornam uma string em vez de preencher um buffer fornecido.

Você não precisa fornecer uma string de formato. Para cada um de Printf, Fprintf e Sprintf existe outro conjunto de funções, por exemplo Print e Println. Essas funções não recebem uma string de formato, mas geram um formato padrão para cada argumento. As versões Println também inserem um espaço entre os argumentos e acrescentam uma quebra de linha à saída, enquanto as versões Print só adicionam espaços quando nenhum dos operandos vizinhos é uma string. Neste exemplo, cada linha produz a mesma saída.

fmt.Printf("Hello %d\n", 23)
fmt.Fprint(os.Stdout, "Hello ", 23, "\n")
fmt.Println("Hello", 23)
fmt.Println(fmt.Sprint("Hello ", 23))

As funções de impressão formatada, como fmt.Fprint e similares, recebem como primeiro argumento qualquer objeto que implemente a interface io.Writer; as variáveis os.Stdout e os.Stderr são exemplos conhecidos.

Aqui as coisas começam a divergir de C. Primeiro, os formatos numéricos, como %d, não recebem flags de sinal ou tamanho; em vez disso, as rotinas de impressão usam o tipo do argumento para decidir essas propriedades.

var x uint64 = 1<<64 - 1
fmt.Printf("%d %x; %d %x\n", x, x, int64(x), int64(x))

imprime

18446744073709551615 ffffffffffffffff; -1 -1

Se você quiser apenas a conversão padrão, como decimal para inteiros, pode usar o formato genérico %v (de “valor”); o resultado é exatamente o que Print e Println produziriam. Além disso, esse formato pode imprimir qualquer valor, até arrays, slices, structs e maps. Aqui está uma instrução de impressão para o map de fusos horários definido na seção anterior.

fmt.Printf("%v\n", timeZone)  // or just fmt.Println(timeZone)

que produz a saída:

map[CST:-21600 EST:-18000 MST:-25200 PST:-28800 UTC:0]

Para maps, Printf e similares ordenam a saída lexicograficamente pela chave.

Ao imprimir uma struct, o formato modificado %+v anota os campos da estrutura com seus nomes, e, para qualquer valor, o formato alternativo %#v imprime o valor em sintaxe Go completa.

type T struct {
    a int
    b float64
    c string
}
t := &T{ 7, -2.35, "abc\tdef" }
fmt.Printf("%v\n", t)
fmt.Printf("%+v\n", t)
fmt.Printf("%#v\n", t)
fmt.Printf("%#v\n", timeZone)

imprime

&{7 -2.35 abc   def}
&{a:7 b:-2.35 c:abc     def}
&main.T{a:7, b:-2.35, c:"abc\tdef"}
map[string]int{"CST":-21600, "EST":-18000, "MST":-25200, "PST":-28800, "UTC":0}

(Observe os e comerciais.) Esse formato de string entre aspas também está disponível por meio de %q quando aplicado a um valor do tipo string ou []byte. O formato alternativo %#q usará crases, se possível. (O formato %q também se aplica a inteiros e runas, produzindo uma constante de runa entre aspas simples.) Além disso, %x funciona com strings, arrays de bytes e slices de bytes, assim como com inteiros, gerando uma longa string hexadecimal, e, com um espaço no formato (% x), ele coloca espaços entre os bytes.

Outro formato útil é %T, que imprime o tipo de um valor.

fmt.Printf("%T\n", timeZone)

imprime

map[string]int

Se você quiser controlar o formato padrão de um tipo personalizado, basta definir um método com a assinatura String() string no tipo. Para o nosso tipo simples T, isso poderia ficar assim.

func (t *T) String() string {
    return fmt.Sprintf("%d/%g/%q", t.a, t.b, t.c)
}
fmt.Printf("%v\n", t)

para imprimir no formato

7/-2.35/"abc\tdef"

(Se você precisar imprimir valores do tipo T e também ponteiros para T, o receptor de String precisa ser do tipo valor; este exemplo usou um ponteiro porque isso é mais eficiente e idiomático para tipos struct. Veja a seção abaixo sobre ponteiros versus receptores por valor para mais informações.)

Nosso método String consegue chamar Sprintf porque as rotinas de impressão são totalmente reentrantes e podem ser encapsuladas dessa forma. Há, porém, um detalhe importante a entender sobre essa abordagem: não construa um método String chamando Sprintf de um jeito que volte a chamar o seu método String indefinidamente. Isso pode acontecer se a chamada a Sprintf tentar imprimir o receptor diretamente como string, o que, por sua vez, invocará o método de novo. É um erro comum e fácil de cometer, como mostra este exemplo.

type MyString string

func (m MyString) String() string {
    return fmt.Sprintf("MyString=%s", m) // Error: will recur forever.
}

Também é fácil de corrigir: converta o argumento para o tipo básico string, que não tem o método.

type MyString string
func (m MyString) String() string {
    return fmt.Sprintf("MyString=%s", string(m)) // OK: note conversion.
}

Na seção de inicialização veremos outra técnica que evita essa recursão.

Outra técnica de impressão é passar os argumentos de uma rotina de impressão diretamente para outra rotina semelhante. A assinatura de Printf usa o tipo ...interface{} para o último argumento, especificando que um número arbitrário de parâmetros (de tipo arbitrário) pode aparecer depois do formato.

func Printf(format string, v ...interface{}) (n int, err error) {

Dentro da função Printf, v se comporta como uma variável do tipo []interface{}, mas, se for passada a outra função variádica, se comporta como uma lista comum de argumentos. Aqui está a implementação da função log.Println que usamos acima. Ela passa seus argumentos diretamente para fmt.Sprintln, que faz a formatação de fato.

// Println prints to the standard logger in the manner of fmt.Println.
func Println(v ...interface{}) {
    std.Output(2, fmt.Sprintln(v...))  // Output takes parameters (int, string)
}

Escrevemos ... depois de v na chamada aninhada a Sprintln para dizer ao compilador que trate v como uma lista de argumentos; caso contrário, ele apenas passaria v como um único argumento do tipo slice.

Há ainda mais coisas sobre impressão do que as que cobrimos aqui. Veja a documentação do godoc do pacote fmt para os detalhes.

A propósito, um parâmetro ... pode ser de um tipo específico, por exemplo ...int para uma função min que escolhe o menor de uma lista de inteiros:

func Min(a ...int) int {
    min := int(^uint(0) >> 1)  // largest int
    for _, i := range a {
        if i < min {
            min = i
        }
    }
    return min
}

Append

Agora temos a peça que faltava para explicar o projeto da função embutida append. A assinatura de append é diferente da nossa função Append personalizada acima. Esquematicamente, ela é assim:

func append(slice []T, elements ...T) []T

onde T é um marcador para qualquer tipo dado. Você não consegue de fato escrever em Go uma função em que o tipo T seja determinado por quem chama. Por isso append é embutida: ela precisa de suporte do compilador.

O que append faz é anexar os elementos ao final do slice e retornar o resultado. O resultado precisa ser retornado porque, assim como na nossa Append escrita à mão, o array subjacente pode mudar. Este exemplo simples

x := []int{1,2,3}
x = append(x, 4, 5, 6)
fmt.Println(x)

imprime [1 2 3 4 5 6]. Assim, append funciona um pouco como Printf, coletando um número arbitrário de argumentos.

Mas e se quiséssemos fazer o que a nossa Append faz e anexar um slice a outro slice? Fácil: use ... no ponto de chamada, assim como fizemos na chamada a Output acima. Este trecho produz a mesma saída do anterior.

x := []int{1,2,3}
y := []int{4,5,6}
x = append(x, y...)
fmt.Println(x)

Sem esse ..., não compilaria, porque os tipos estariam errados; y não é do tipo int.

Inicialização

Embora, à primeira vista, não pareça muito diferente da inicialização em C ou C++, a inicialização em Go é mais poderosa. Estruturas complexas podem ser construídas durante a inicialização, e as questões de ordem entre objetos inicializados, mesmo entre pacotes diferentes, são tratadas corretamente.

Constantes

Constantes em Go são exatamente isso: constantes. Elas são criadas em tempo de compilação, mesmo quando definidas como variáveis locais em funções, e só podem ser números, caracteres (runas), strings ou booleanos. Por causa da restrição de tempo de compilação, as expressões que as definem precisam ser expressões constantes, avaliáveis pelo compilador. Por exemplo, 1<<3 é uma expressão constante, enquanto math.Sin(math.Pi/4) não é, porque a chamada de função a math.Sin precisa acontecer em tempo de execução.

Em Go, constantes enumeradas são criadas com o enumerador iota. Como iota pode fazer parte de uma expressão e expressões podem ser repetidas implicitamente, é fácil construir conjuntos complexos de valores.

type ByteSize float64

const (
    _           = iota // ignore first value by assigning to blank identifier
    KB ByteSize = 1 << (10 * iota)
    MB
    GB
    TB
    PB
    EB
    ZB
    YB
)

A capacidade de anexar um método como String a qualquer tipo definido pelo usuário torna possível que valores arbitrários se formatem automaticamente para impressão. Embora você veja isso com mais frequência aplicado a structs, essa técnica também é útil para tipos escalares, como os de ponto flutuante, por exemplo ByteSize.

func (b ByteSize) String() string {
    switch {
    case b >= YB:
        return fmt.Sprintf("%.2fYB", b/YB)
    case b >= ZB:
        return fmt.Sprintf("%.2fZB", b/ZB)
    case b >= EB:
        return fmt.Sprintf("%.2fEB", b/EB)
    case b >= PB:
        return fmt.Sprintf("%.2fPB", b/PB)
    case b >= TB:
        return fmt.Sprintf("%.2fTB", b/TB)
    case b >= GB:
        return fmt.Sprintf("%.2fGB", b/GB)
    case b >= MB:
        return fmt.Sprintf("%.2fMB", b/MB)
    case b >= KB:
        return fmt.Sprintf("%.2fKB", b/KB)
    }
    return fmt.Sprintf("%.2fB", b)
}

A expressão YB é impressa como 1.00YB, enquanto ByteSize(1e13) é impresso como 9.09TB.

O uso de Sprintf aqui para implementar o método String de ByteSize é seguro (evita a recursão infinita) não por causa de uma conversão, mas porque chama Sprintf com %f, que não é um formato de string: Sprintf só vai chamar o método String quando quiser uma string, e %f quer um valor de ponto flutuante.

Variáveis

Variáveis podem ser inicializadas da mesma forma que constantes, mas o inicializador pode ser uma expressão geral calculada em tempo de execução.

var (
    home   = os.Getenv("HOME")
    user   = os.Getenv("USER")
    gopath = os.Getenv("GOPATH")
)

A função init

Por fim, cada arquivo-fonte pode definir sua própria função init, sem parâmetros, para preparar o estado que for necessário. (Na verdade, cada arquivo pode ter várias funções init.) E "por fim" quer dizer por fim mesmo: init é chamada depois que todas as declarações de variáveis do pacote avaliaram seus inicializadores, e estas só são avaliadas depois que todos os pacotes importados foram inicializados.

Além das inicializações que não podem ser expressas como declarações, um uso comum das funções init é verificar ou corrigir a consistência do estado do programa antes de a execução de fato começar.

func init() {
    if user == "" {
        log.Fatal("$USER not set")
    }
    if home == "" {
        home = "/home/" + user
    }
    if gopath == "" {
        gopath = home + "/go"
    }
    // gopath may be overridden by --gopath flag on command line.
    flag.StringVar(&gopath, "gopath", gopath, "override default GOPATH")
}

Métodos

Ponteiros versus valores

Como vimos com ByteSize, métodos podem ser definidos para qualquer tipo nomeado (exceto um ponteiro ou uma interface); o receptor não precisa ser uma struct.

Na discussão sobre slices acima, escrevemos uma função Append. Podemos defini-la como um método em slices. Para isso, primeiro declaramos um tipo nomeado ao qual possamos vincular o método, e depois tornamos o receptor do método um valor desse tipo.

type ByteSlice []byte

func (slice ByteSlice) Append(data []byte) []byte {
    // Body exactly the same as the Append function defined above.
}

Isso ainda exige que o método retorne o slice atualizado. Podemos eliminar essa desajeitação redefinindo o método para receber, como receptor, um ponteiro para ByteSlice, de modo que o método possa sobrescrever o slice de quem chamou.

func (p *ByteSlice) Append(data []byte) {
    slice := *p
    // Body as above, without the return.
    *p = slice
}

Na verdade, podemos fazer ainda melhor. Se modificarmos nossa função para que ela pareça com um método Write padrão, assim,

func (p *ByteSlice) Write(data []byte) (n int, err error) {
    slice := *p
    // Again as above.
    *p = slice
    return len(data), nil
}

então o tipo *ByteSlice satisfaz a interface padrão io.Writer, o que é útil. Por exemplo, podemos imprimir dentro dele.

    var b ByteSlice
    fmt.Fprintf(&b, "This hour has %d days\n", 7)

Passamos o endereço de um ByteSlice porque apenas *ByteSlice satisfaz io.Writer. A regra sobre ponteiros versus valores para receptores é que métodos com receptor de valor podem ser invocados em ponteiros e valores, mas métodos com receptor de ponteiro só podem ser invocados em ponteiros.

Essa regra existe porque métodos com ponteiro podem modificar o receptor; invocá-los sobre um valor faria o método receber uma cópia do valor, então quaisquer modificações seriam descartadas. Por isso a linguagem proíbe esse erro. Há, porém, uma exceção útil. Quando o valor é endereçável, a linguagem cuida do caso comum de invocar um método com ponteiro sobre um valor, inserindo automaticamente o operador de endereço. No nosso exemplo, a variável b é endereçável, então podemos chamar o método Write dela apenas com b.Write. O compilador reescreve isso para (&b).Write para nós.

A propósito, a ideia de usar Write sobre um slice de bytes é central para a implementação de bytes.Buffer.

Interfaces e outros tipos

Interfaces

Interfaces em Go oferecem uma forma de especificar o comportamento de um objeto: se algo pode fazer isto, então ele pode ser usado aqui. Já vimos alguns exemplos simples; impressores personalizados podem ser implementados por um método String, enquanto Fprintf pode gerar saída para qualquer coisa com um método Write. Interfaces com apenas um ou dois métodos são comuns no código Go, e normalmente recebem um nome derivado do método, como io.Writer para algo que implementa Write.

Um tipo pode implementar várias interfaces. Por exemplo, uma coleção pode ser ordenada pelas rotinas do pacote sort se implementar sort.Interface, que contém Len(), Less(i, j int) bool e Swap(i, j int), e também poderia ter um formatador personalizado. Neste exemplo artificial, Sequence satisfaz as duas.

type Sequence []int

// Methods required by sort.Interface.
func (s Sequence) Len() int {
    return len(s)
}
func (s Sequence) Less(i, j int) bool {
    return s[i] < s[j]
}
func (s Sequence) Swap(i, j int) {
    s[i], s[j] = s[j], s[i]
}

// Copy returns a copy of the Sequence.
func (s Sequence) Copy() Sequence {
    copy := make(Sequence, 0, len(s))
    return append(copy, s...)
}

// Method for printing - sorts the elements before printing.
func (s Sequence) String() string {
    s = s.Copy() // Make a copy; don't overwrite argument.
    sort.Sort(s)
    str := "["
    for i, elem := range s { // Loop is O(N²); will fix that in next example.
        if i > 0 {
            str += " "
        }
        str += fmt.Sprint(elem)
    }
    return str + "]"
}

Conversões

O método String de Sequence está refazendo o trabalho que Sprint já faz para slices. (Ele também tem complexidade O(N²), o que é ruim.) Podemos dividir o esforço (e ainda acelerar) se convertermos o Sequence para um []int simples antes de chamar Sprint.

func (s Sequence) String() string {
    s = s.Copy()
    sort.Sort(s)
    return fmt.Sprint([]int(s))
}

Este método é outro exemplo da técnica de conversão para chamar Sprintf com segurança a partir de um método String. Como os dois tipos (Sequence e []int) são iguais se ignorarmos o nome do tipo, é válido converter entre eles. A conversão não cria um novo valor; ela apenas age temporariamente como se o valor existente tivesse um novo tipo. (Há outras conversões válidas, como de inteiro para ponto flutuante, que criam um novo valor.)

É um idioma em programas Go converter o tipo de uma expressão para acessar um conjunto diferente de métodos. Como exemplo, poderíamos usar o tipo existente sort.IntSlice para reduzir todo o exemplo a isto:

type Sequence []int

// Method for printing - sorts the elements before printing
func (s Sequence) String() string {
    s = s.Copy()
    sort.IntSlice(s).Sort()
    return fmt.Sprint([]int(s))
}

Agora, em vez de fazer Sequence implementar várias interfaces (ordenação e impressão), estamos usando a capacidade de um item de dados ser convertido em vários tipos (Sequence, sort.IntSlice e []int), cada um dos quais faz uma parte do trabalho. Isso é mais incomum na prática, mas pode ser eficaz.

Conversões de interface e asserções de tipo

Switches de tipo são uma forma de conversão: eles recebem uma interface e, para cada caso do switch, em certo sentido a convertem para o tipo desse caso. Aqui está uma versão simplificada de como o código sob fmt.Printf transforma um valor em uma string usando um switch de tipo. Se já for uma string, queremos o valor de string real guardado pela interface; se tiver um método String, queremos o resultado da chamada do método.

type Stringer interface {
    String() string
}

var value interface{} // Value provided by caller.
switch str := value.(type) {
case string:
    return str
case Stringer:
    return str.String()
}

O primeiro caso encontra um valor concreto; o segundo converte a interface em outra interface. É perfeitamente válido misturar tipos dessa forma.

E se houver apenas um tipo que nos interessa? Se soubermos que o valor guarda uma string e quisermos apenas extraí-la? Um switch de tipo com um único caso serviria, mas uma asserção de tipo também. Uma asserção de tipo recebe um valor de interface e extrai dele um valor do tipo explícito especificado. A sintaxe toma emprestada a cláusula que abre um switch de tipo, mas com um tipo explícito em vez da palavra-chave type:

value.(typeName)

e o resultado é um novo valor com o tipo estático typeName. Esse tipo deve ser o tipo concreto guardado pela interface, ou um segundo tipo de interface para o qual o valor possa ser convertido. Para extrair a string que sabemos estar no valor, podemos escrever:

str := value.(string)

Mas se acontecer de o valor não conter uma string, o programa vai travar com um erro de tempo de execução. Para se proteger disso, use o idioma "vírgula, ok" para testar, com segurança, se o valor é uma string:

str, ok := value.(string)
if ok {
    fmt.Printf("string value is: %q\n", str)
} else {
    fmt.Printf("value is not a string\n")
}

Se a asserção de tipo falhar, str continuará existindo e será do tipo string, mas terá o valor zero, uma string vazia.

Como ilustração da capacidade, aqui está uma instrução if-else equivalente ao switch de tipo que abriu esta seção.

if str, ok := value.(string); ok {
    return str
} else if str, ok := value.(Stringer); ok {
    return str.String()
}

Generalidade

Se um tipo existe apenas para implementar uma interface e nunca terá métodos exportados além dessa interface, não há necessidade de exportar o próprio tipo. Exportar apenas a interface deixa claro que o valor não tem nenhum comportamento interessante além do que está descrito na interface. Isso também evita a necessidade de repetir a documentação em cada instância de um método comum.

Nesses casos, o construtor deve retornar um valor de interface em vez do tipo que implementa a interface. Por exemplo, nas bibliotecas de hash, tanto crc32.NewIEEE quanto adler32.New retornam o tipo de interface hash.Hash32. Trocar o algoritmo CRC-32 pelo Adler-32 em um programa Go exige apenas mudar a chamada do construtor; o restante do código não é afetado pela troca do algoritmo.

Uma abordagem semelhante permite que os algoritmos de cifra de fluxo nos vários pacotes crypto sejam separados das cifras de bloco que eles encadeiam. A interface Block no pacote crypto/cipher especifica o comportamento de uma cifra de bloco, que faz a cifragem de um único bloco de dados. Então, por analogia com o pacote bufio, pacotes de cifra que implementam essa interface podem ser usados para construir cifras de fluxo, representadas pela interface Stream, sem conhecer os detalhes da cifragem de blocos.

As interfaces de crypto/cipher são assim:

type Block interface {
    BlockSize() int
    Encrypt(dst, src []byte)
    Decrypt(dst, src []byte)
}

type Stream interface {
    XORKeyStream(dst, src []byte)
}

Aqui está a definição do fluxo em modo contador (CTR), que transforma uma cifra de bloco em uma cifra de fluxo; observe que os detalhes da cifra de bloco são abstraídos:

// NewCTR returns a Stream that encrypts/decrypts using the given Block in
// counter mode. The length of iv must be the same as the Block's block size.
func NewCTR(block Block, iv []byte) Stream

NewCTR se aplica não apenas a um algoritmo de cifragem e fonte de dados específicos, mas a qualquer implementação da interface Block e a qualquer Stream. Como retornam valores de interface, trocar a cifragem CTR por outros modos de cifragem é uma mudança localizada. Os construtores precisam ser editados, mas, como o código ao redor deve tratar o resultado apenas como um Stream, ele não percebe a diferença.

Interfaces e métodos

Como quase qualquer coisa pode ter métodos anexados, quase qualquer coisa pode satisfazer uma interface. Um exemplo ilustrativo está no pacote http, que define a interface Handler. Qualquer objeto que implemente Handler pode atender requisições HTTP.

type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}

ResponseWriter é ela mesma uma interface que dá acesso aos métodos necessários para devolver a resposta ao cliente. Esses métodos incluem o método padrão Write, então um http.ResponseWriter pode ser usado em qualquer lugar onde um io.Writer pode ser usado. Request é uma struct que contém uma representação analisada da requisição do cliente.

Por brevidade, vamos ignorar os POSTs e supor que as requisições HTTP são sempre GETs; essa simplificação não afeta a forma como os handlers são configurados. Aqui está uma implementação trivial de um handler que conta quantas vezes a página foi visitada.

// Simple counter server.
type Counter struct {
    n int
}

func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
    ctr.n++
    fmt.Fprintf(w, "counter = %d\n", ctr.n)
}

(Seguindo o nosso tema, observe como Fprintf pode imprimir em um http.ResponseWriter.) Em um servidor real, o acesso a ctr.n precisaria de proteção contra acesso concorrente. Veja os pacotes sync e atomic para sugestões.

Para referência, veja como anexar esse servidor a um nó da árvore de URLs.

import "net/http"
...
ctr := new(Counter)
http.Handle("/counter", ctr)

Mas por que tornar Counter uma struct? Um inteiro é tudo o que é necessário. (O receptor precisa ser um ponteiro para que o incremento seja visível para quem chama.)

// Simpler counter server.
type Counter int

func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
    *ctr++
    fmt.Fprintf(w, "counter = %d\n", *ctr)
}

E se o seu programa tiver algum estado interno que precisa ser notificado de que uma página foi visitada? Associe um canal à página web.

// A channel that sends a notification on each visit.
// (Probably want the channel to be buffered.)
type Chan chan *http.Request

func (ch Chan) ServeHTTP(w http.ResponseWriter, req *http.Request) {
    ch <- req
    fmt.Fprint(w, "notification sent")
}

Por fim, digamos que quiséssemos apresentar em /args os argumentos usados ao invocar o binário do servidor. É fácil escrever uma função para imprimir os argumentos.

func ArgServer() {
    fmt.Println(os.Args)
}

Como transformar isso em um servidor HTTP? Poderíamos tornar ArgServer um método de algum tipo cujo valor ignoramos, mas há um jeito mais limpo. Como podemos definir um método para qualquer tipo exceto ponteiros e interfaces, podemos escrever um método para uma função. O pacote http contém este código:

// The HandlerFunc type is an adapter to allow the use of
// ordinary functions as HTTP handlers.  If f is a function
// with the appropriate signature, HandlerFunc(f) is a
// Handler object that calls f.
type HandlerFunc func(ResponseWriter, *Request)

// ServeHTTP calls f(w, req).
func (f HandlerFunc) ServeHTTP(w ResponseWriter, req *Request) {
    f(w, req)
}

HandlerFunc é um tipo com um método, ServeHTTP, então valores desse tipo podem atender requisições HTTP. Observe a implementação do método: o receptor é uma função, f, e o método chama f. Pode parecer estranho, mas não é tão diferente de, digamos, o receptor ser um canal e o método enviar para o canal.

Para transformar ArgServer em um servidor HTTP, primeiro a modificamos para ter a assinatura certa.

// Argument server.
func ArgServer(w http.ResponseWriter, req *http.Request) {
    fmt.Fprintln(w, os.Args)
}

ArgServer agora tem a mesma assinatura de HandlerFunc, então pode ser convertida para esse tipo para acessar seus métodos, assim como convertemos Sequence para IntSlice para acessar IntSlice.Sort. O código para configurar isso é conciso:

http.Handle("/args", http.HandlerFunc(ArgServer))

Quando alguém visita a página /args, o handler instalado nessa página tem o valor ArgServer e o tipo HandlerFunc. O servidor HTTP vai invocar o método ServeHTTP desse tipo, com ArgServer como receptor, que por sua vez vai chamar ArgServer (pela invocação f(w, req) dentro de HandlerFunc.ServeHTTP). Os argumentos serão então exibidos.

Nesta seção, fizemos um servidor HTTP a partir de uma struct, de um inteiro, de um canal e de uma função, tudo isso porque interfaces são apenas conjuntos de métodos, que podem ser definidos para (quase) qualquer tipo.

O identificador em branco

Já mencionamos o identificador em branco algumas vezes, no contexto de laços for range e maps. O identificador em branco pode ser atribuído ou declarado com qualquer valor de qualquer tipo, com o valor descartado sem problemas. É um pouco como escrever no arquivo /dev/null do Unix: ele representa um valor somente de escrita usado como marcador onde uma variável é necessária, mas o valor real é irrelevante. Ele tem usos além dos que já vimos.

O identificador em branco em atribuição múltipla

O uso de um identificador em branco em um laço for range é um caso particular de uma situação geral: a atribuição múltipla.

Se uma atribuição exigir vários valores do lado esquerdo, mas um dos valores não for usado pelo programa, um identificador em branco do lado esquerdo da atribuição evita a necessidade de criar uma variável fictícia e deixa claro que o valor será descartado. Por exemplo, ao chamar uma função que retorna um valor e um erro, mas só o erro importa, use o identificador em branco para descartar o valor irrelevante.

if _, err := os.Stat(path); os.IsNotExist(err) {
    fmt.Printf("%s does not exist\n", path)
}

Às vezes você verá código que descarta o valor de erro para ignorar o erro; isso é uma péssima prática. Sempre verifique os erros retornados; eles existem por um motivo.

// Bad! This code will crash if path does not exist.
fi, _ := os.Stat(path)
if fi.IsDir() {
    fmt.Printf("%s is a directory\n", path)
}

Importações e variáveis não usadas

É erro importar um pacote ou declarar uma variável sem usá-la. Importações não usadas incham o programa e deixam a compilação mais lenta, enquanto uma variável inicializada mas não usada é, no mínimo, um cálculo desperdiçado e talvez um indício de um bug maior. Quando um programa está em desenvolvimento ativo, porém, importações e variáveis não usadas surgem com frequência, e pode ser irritante apagá-las só para a compilação prosseguir, para depois precisar delas de novo. O identificador em branco oferece uma solução alternativa.

Este programa meio escrito tem duas importações não usadas (fmt e io) e uma variável não usada (fd), então não vai compilar, mas seria bom ver se o código até agora está correto.

package main

import (
    "fmt"
    "io"
    "log"
    "os"
)

func main() {
    fd, err := os.Open("test.go")
    if err != nil {
        log.Fatal(err)
    }
    // TODO: use fd.
}

Para silenciar as reclamações sobre as importações não usadas, use um identificador em branco para se referir a um símbolo do pacote importado. De modo semelhante, atribuir a variável não usada fd ao identificador em branco silenciará o erro de variável não usada. Esta versão do programa compila.

package main

import (
    "fmt"
    "io"
    "log"
    "os"
)

var _ = fmt.Printf // For debugging; delete when done.
var _ io.Reader    // For debugging; delete when done.

func main() {
    fd, err := os.Open("test.go")
    if err != nil {
        log.Fatal(err)
    }
    // TODO: use fd.
    _ = fd
}

Por convenção, as declarações globais que silenciam erros de importação devem vir logo após as importações e ser comentadas, tanto para facilitar encontrá-las quanto como lembrete para limpar tudo depois.

Importação por efeito colateral

Uma importação não usada, como fmt ou io no exemplo anterior, deve eventualmente ser usada ou removida: atribuições em branco identificam o código como um trabalho em andamento. Mas às vezes é útil importar um pacote apenas por seus efeitos colaterais, sem nenhum uso explícito. Por exemplo, durante a sua função init, o pacote net/http/pprof registra handlers HTTP que fornecem informações de depuração. Ele tem uma API exportada, mas a maioria dos clientes precisa apenas do registro dos handlers e acessa os dados por uma página web. Para importar o pacote apenas por seus efeitos colaterais, renomeie o pacote para o identificador em branco:

import _ "net/http/pprof"

Essa forma de importação deixa claro que o pacote está sendo importado por seus efeitos colaterais, pois não há outro uso possível para o pacote: neste arquivo, ele não tem nome. (Se tivesse, e não usássemos esse nome, o compilador rejeitaria o programa.)

Verificações de interface

Como vimos na discussão sobre interfaces acima, um tipo não precisa declarar explicitamente que implementa uma interface. Em vez disso, um tipo implementa a interface apenas ao implementar os métodos da interface. Na prática, a maioria das conversões de interface é estática e, portanto, verificada em tempo de compilação. Por exemplo, passar um *os.File para uma função que espera um io.Reader não compila a menos que *os.File implemente a interface io.Reader.

Algumas verificações de interface, porém, acontecem em tempo de execução. Um exemplo está no pacote encoding/json, que define uma interface Marshaler. Quando o codificador JSON recebe um valor que implementa essa interface, ele invoca o método de serialização do valor para convertê-lo em JSON, em vez de fazer a conversão padrão. O codificador verifica essa propriedade em tempo de execução com uma asserção de tipo como:

m, ok := val.(json.Marshaler)

Se for necessário apenas perguntar se um tipo implementa uma interface, sem de fato usar a própria interface, talvez como parte de uma verificação de erro, use o identificador em branco para ignorar o valor da asserção de tipo:

if _, ok := val.(json.Marshaler); ok {
    fmt.Printf("value %v of type %T implements json.Marshaler\n", val, val)
}

Uma situação em que isso acontece é quando é preciso garantir, dentro do pacote que implementa o tipo, que ele realmente satisfaz a interface. Se um tipo—por exemplo, json.RawMessage—precisar de uma representação JSON personalizada, ele deve implementar json.Marshaler, mas não há conversões estáticas que fariam o compilador verificar isso automaticamente. Se o tipo não satisfizer a interface por descuido, o codificador JSON ainda vai funcionar, mas não vai usar a implementação personalizada. Para garantir que a implementação está correta, pode-se usar, no pacote, uma declaração global com o identificador em branco:

var _ json.Marshaler = (*RawMessage)(nil)

Nessa declaração, a atribuição que envolve a conversão de um *RawMessage para um Marshaler exige que *RawMessage implemente Marshaler, e essa propriedade será verificada em tempo de compilação. Se a interface json.Marshaler mudar, este pacote deixará de compilar e saberemos que ele precisa ser atualizado.

A presença do identificador em branco nessa construção indica que a declaração existe apenas para a verificação de tipos, e não para criar uma variável. Não faça isso para todo tipo que satisfaz uma interface, porém. Por convenção, essas declarações só são usadas quando não há conversões estáticas já presentes no código, o que é um evento raro.

Incorporação

Go não oferece a noção típica de herança baseada em tipo (subclasses), mas tem a capacidade de “tomar emprestados” pedaços de uma implementação ao incorporar tipos dentro de uma struct ou interface.

A incorporação de interfaces é muito simples. Já mencionamos as interfaces io.Reader e io.Writer; aqui estão as definições delas.

type Reader interface {
    Read(p []byte) (n int, err error)
}

type Writer interface {
    Write(p []byte) (n int, err error)
}

O pacote io também exporta várias outras interfaces que especificam objetos que podem implementar vários desses métodos. Por exemplo, há io.ReadWriter, uma interface que contém tanto Read quanto Write. Poderíamos especificar io.ReadWriter listando os dois métodos explicitamente, mas é mais fácil e mais expressivo incorporar as duas interfaces para formar a nova, assim:

// ReadWriter is the interface that combines the Reader and Writer interfaces.
type ReadWriter interface {
    Reader
    Writer
}

Isso diz exatamente o que parece: um ReadWriter pode fazer o que um Reader faz e o que um Writer faz; é uma união das interfaces incorporadas. Só interfaces podem ser incorporadas dentro de interfaces.

A mesma ideia básica se aplica a structs, mas com implicações mais amplas. O pacote bufio tem dois tipos struct, bufio.Reader e bufio.Writer, cada um dos quais, naturalmente, implementa as interfaces análogas do pacote io. E o bufio também implementa um leitor/escritor com buffer, o que faz combinando um leitor e um escritor em uma única struct por meio de incorporação: ele lista os tipos dentro da struct, mas não dá nomes de campo a eles.

// ReadWriter stores pointers to a Reader and a Writer.
// It implements io.ReadWriter.
type ReadWriter struct {
    *Reader  // *bufio.Reader
    *Writer  // *bufio.Writer
}

Os elementos incorporados são ponteiros para structs e, naturalmente, precisam ser inicializados para apontar para structs válidas antes de poderem ser usados. A struct ReadWriter poderia ser escrita como

type ReadWriter struct {
    reader *Reader
    writer *Writer
}

mas então, para promover os métodos dos campos e satisfazer as interfaces de io, também precisaríamos fornecer métodos de encaminhamento, assim:

func (rw *ReadWriter) Read(p []byte) (n int, err error) {
    return rw.reader.Read(p)
}

Ao incorporar as structs diretamente, evitamos essa contabilidade. Os métodos dos tipos incorporados vêm de graça, o que significa que bufio.ReadWriter não apenas tem os métodos de bufio.Reader e bufio.Writer, como também satisfaz as três interfaces: io.Reader, io.Writer e io.ReadWriter.

Há uma forma importante em que a incorporação difere da herança. Quando incorporamos um tipo, os métodos desse tipo se tornam métodos do tipo externo, mas, quando são invocados, o receptor do método é o tipo interno, e não o externo. No nosso exemplo, quando o método Read de um bufio.ReadWriter é invocado, ele tem exatamente o mesmo efeito do método de encaminhamento escrito acima; o receptor é o campo reader do ReadWriter, e não o próprio ReadWriter.

A incorporação também pode ser uma conveniência simples. Este exemplo mostra um campo incorporado ao lado de um campo comum, nomeado.

type Job struct {
    Command string
    *log.Logger
}

O tipo Job agora tem os métodos Print, Printf, Println e os outros métodos de *log.Logger. Poderíamos ter dado ao Logger um nome de campo, claro, mas não é necessário. E agora, uma vez inicializado, podemos registrar mensagens no Job:

job.Println("starting now...")

O Logger é um campo comum da struct Job, então podemos inicializá-lo da forma usual dentro do construtor de Job, assim,

func NewJob(command string, logger *log.Logger) *Job {
    return &Job{command, logger}
}

ou com um literal composto,

job := &Job{command, log.New(os.Stderr, "Job: ", log.Ldate)}

Se precisarmos nos referir a um campo incorporado diretamente, o nome do tipo do campo, desconsiderando o qualificador do pacote, serve como nome de campo, como fez no método Read da nossa struct ReadWriter. Aqui, se precisássemos acessar o *log.Logger de uma variável job do tipo Job, escreveríamos job.Logger, o que seria útil se quiséssemos refinar os métodos de Logger.

func (job *Job) Printf(format string, args ...interface{}) {
    job.Logger.Printf("%q: %s", job.Command, fmt.Sprintf(format, args...))
}

Incorporar tipos introduz o problema de conflitos de nomes, mas as regras para resolvê-los são simples. Primeiro, um campo ou método X oculta qualquer outro item X em uma parte mais profundamente aninhada do tipo. Se log.Logger tivesse um campo ou método chamado Command, o campo Command de Job prevaleceria sobre ele.

Segundo, se o mesmo nome aparecer no mesmo nível de aninhamento, geralmente é um erro; seria errado incorporar log.Logger se a struct Job tivesse outro campo ou método chamado Logger. No entanto, se o nome duplicado nunca for mencionado no programa fora da definição do tipo, não há problema. Essa qualificação oferece alguma proteção contra mudanças feitas em tipos incorporados de fora; não há problema se um campo for adicionado e entrar em conflito com outro campo de outro subtipo, desde que nenhum dos dois seja usado.

Concorrência

Compartilhe comunicando

Programação concorrente é um assunto amplo, e há espaço aqui apenas para alguns destaques específicos de Go.

A programação concorrente em muitos ambientes é dificultada pelas sutilezas necessárias para implementar um acesso correto a variáveis compartilhadas. Go incentiva uma abordagem diferente, na qual valores compartilhados são passados por canais e, na verdade, nunca são ativamente compartilhados por threads de execução separadas. Apenas uma goroutine tem acesso ao valor em um dado momento. Condições de corrida (data races) não podem ocorrer, por design. Para incentivar essa forma de pensar, a reduzimos a um lema:

Não se comunique compartilhando memória; em vez disso, compartilhe memória comunicando.

Essa abordagem pode ser levada longe demais. Contadores de referência podem ser melhor implementados colocando um mutex em torno de uma variável inteira, por exemplo. Mas, como uma abordagem de alto nível, usar canais para controlar o acesso torna mais fácil escrever programas claros e corretos.

Uma forma de pensar sobre esse modelo é considerar um programa típico de thread única rodando em uma CPU. Ele não precisa de primitivas de sincronização. Agora execute outra instância desse tipo; ela também não precisa de sincronização. Agora faça as duas se comunicarem; se a comunicação for o sincronizador, ainda não há necessidade de qualquer outra sincronização. Pipelines do Unix, por exemplo, se encaixam perfeitamente nesse modelo. Embora a abordagem de Go para concorrência tenha origem nos Communicating Sequential Processes (CSP) de Hoare, ela também pode ser vista como uma generalização, com segurança de tipos, dos pipes do Unix.

Goroutines

Elas se chamam goroutines porque os termos existentes—threads, corrotinas, processos e assim por diante—transmitem conotações imprecisas. Uma goroutine tem um modelo simples: é uma função executada concorrentemente com outras goroutines no mesmo espaço de endereçamento. É leve, custando pouco mais que a alocação de espaço de pilha. E as pilhas começam pequenas, então são baratas, e crescem alocando (e liberando) armazenamento na heap conforme necessário.

As goroutines são multiplexadas em várias threads do sistema operacional, então, se uma delas bloquear, como ao aguardar E/S, as outras continuam rodando. O design delas esconde muitas das complexidades da criação e do gerenciamento de threads.

Coloque a palavra-chave go antes de uma chamada de função ou método para executar a chamada em uma nova goroutine. Quando a chamada termina, a goroutine sai silenciosamente. (O efeito é semelhante à notação & do shell do Unix para executar um comando em segundo plano.)

go list.Sort()  // run list.Sort concurrently; don't wait for it.

Um literal de função pode ser útil na invocação de uma goroutine.

func Announce(message string, delay time.Duration) {
    go func() {
        time.Sleep(delay)
        fmt.Println(message)
    }()  // Note the parentheses - must call the function.
}

Em Go, literais de função são closures: a implementação garante que as variáveis referenciadas pela função sobrevivam enquanto estiverem ativas.

Esses exemplos não são muito práticos porque as funções não têm como sinalizar a conclusão. Para isso, precisamos de canais.

Canais

Assim como os maps, canais são alocados com make, e o valor resultante funciona como uma referência a uma estrutura de dados subjacente. Se um parâmetro inteiro opcional for fornecido, ele define o tamanho do buffer do canal. O padrão é zero, para um canal sem buffer, ou síncrono.

ci := make(chan int)            // unbuffered channel of integers
cj := make(chan int, 0)         // unbuffered channel of integers
cs := make(chan *os.File, 100)  // buffered channel of pointers to Files

Canais sem buffer combinam comunicação—a troca de um valor—com sincronização—garantindo que dois cálculos (goroutines) estejam em um estado conhecido.

Há muitos idiomas bons usando canais. Aqui está um para começar. Na seção anterior, lançamos uma ordenação em segundo plano. Um canal pode permitir que a goroutine que a lançou espere a ordenação terminar.

c := make(chan int)  // Allocate a channel.
// Start the sort in a goroutine; when it completes, signal on the channel.
go func() {
    list.Sort()
    c <- 1  // Send a signal; value does not matter.
}()
doSomethingForAWhile()
<-c   // Wait for sort to finish; discard sent value.

Receptores sempre bloqueiam até que haja dados para receber. Se o canal não tiver buffer, o remetente bloqueia até que o receptor tenha recebido o valor. Se o canal tiver buffer, o remetente bloqueia apenas até que o valor tenha sido copiado para o buffer; se o buffer estiver cheio, isso significa esperar até algum receptor retirar um valor.

Um canal com buffer pode ser usado como um semáforo, por exemplo para limitar a vazão. Neste exemplo, as requisições recebidas são passadas para handle, que envia um valor para o canal, processa a requisição e, em seguida, recebe um valor do canal para liberar o “semáforo” para o próximo consumidor. A capacidade do buffer do canal limita o número de chamadas simultâneas a process.

var sem = make(chan int, MaxOutstanding)

func handle(r *Request) {
    sem <- 1    // Wait for active queue to drain.
    process(r)  // May take a long time.
    <-sem       // Done; enable next request to run.
}

func Serve(queue chan *Request) {
    for {
        req := <-queue
        go handle(req)  // Don't wait for handle to finish.
    }
}

Quando MaxOutstanding handlers estiverem executando process, quaisquer outros vão bloquear tentando enviar para o buffer cheio do canal, até que um dos handlers existentes termine e receba do buffer.

Este design tem um problema, porém: Serve cria uma nova goroutine para cada requisição recebida, embora apenas MaxOutstanding delas possam rodar a qualquer momento. Como resultado, o programa pode consumir recursos ilimitados se as requisições chegarem rápido demais. Podemos corrigir essa deficiência alterando Serve para controlar a criação das goroutines:

func Serve(queue chan *Request) {
    for req := range queue {
        sem <- 1
        go func() {
            process(req)
            <-sem
        }()
    }
}

(Observe que, nas versões do Go anteriores à 1.22, este código tem um bug: a variável do laço é compartilhada por todas as goroutines. Veja o wiki do Go para detalhes.)

Outra abordagem que gerencia bem os recursos é iniciar um número fixo de goroutines handle, todas lendo do canal de requisições. O número de goroutines limita o número de chamadas simultâneas a process. Esta função Serve também aceita um canal pelo qual será avisada para sair; depois de iniciar as goroutines, ela bloqueia recebendo desse canal.

func handle(queue chan *Request) {
    for r := range queue {
        process(r)
    }
}

func Serve(clientRequests chan *Request, quit chan bool) {
    // Start handlers
    for i := 0; i < MaxOutstanding; i++ {
        go handle(clientRequests)
    }
    <-quit  // Wait to be told to exit.
}

Canais de canais

Uma das propriedades mais importantes de Go é que um canal é um valor de primeira classe, que pode ser alocado e passado como qualquer outro. Um uso comum dessa propriedade é implementar uma demultiplexação paralela e segura.

No exemplo da seção anterior, handle era um handler idealizado para uma requisição, mas não definimos o tipo que ele tratava. Se esse tipo incluir um canal pelo qual responder, cada cliente pode fornecer seu próprio caminho para a resposta. Aqui está uma definição esquemática do tipo Request.

type Request struct {
    args        []int
    f           func([]int) int
    resultChan  chan int
}

O cliente fornece uma função e seus argumentos, além de um canal dentro do objeto de requisição pelo qual receber a resposta.

func sum(a []int) (s int) {
    for _, v := range a {
        s += v
    }
    return
}

request := &Request{[]int{3, 4, 5}, sum, make(chan int)}
// Send request
clientRequests <- request
// Wait for response.
fmt.Printf("answer: %d\n", <-request.resultChan)

Do lado do servidor, a função handler é a única coisa que muda.

func handle(queue chan *Request) {
    for req := range queue {
        req.resultChan <- req.f(req.args)
    }
}

Claramente há muito mais a fazer para torná-lo realista, mas este código é um esqueleto para um sistema RPC com limite de taxa, paralelo e não bloqueante, e não há um mutex à vista.

Paralelização

Outra aplicação dessas ideias é paralelizar um cálculo entre vários núcleos de CPU. Se o cálculo puder ser dividido em partes separadas que possam ser executadas de forma independente, ele pode ser paralelizado, com um canal para sinalizar quando cada parte termina.

Digamos que temos uma operação cara a ser realizada sobre um vetor de itens, e que o valor da operação em cada item é independente, como neste exemplo idealizado.

type Vector []float64

// Apply the operation to v[i], v[i+1] ... up to v[n-1].
func (v Vector) DoSome(i, n int, u Vector, c chan int) {
    for ; i < n; i++ {
        v[i] += u.Op(v[i])
    }
    c <- 1    // signal that this piece is done
}

Lançamos as partes de forma independente em um laço, uma por CPU. Elas podem terminar em qualquer ordem, mas isso não importa; apenas contamos os sinais de conclusão esvaziando o canal depois de lançar todas as goroutines.

const numCPU = 4 // number of CPU cores

func (v Vector) DoAll(u Vector) {
    c := make(chan int, numCPU)  // Buffering optional but sensible.
    for i := 0; i < numCPU; i++ {
        go v.DoSome(i*len(v)/numCPU, (i+1)*len(v)/numCPU, u, c)
    }
    // Drain the channel.
    for i := 0; i < numCPU; i++ {
        <-c    // wait for one task to complete
    }
    // All done.
}

Em vez de criar um valor constante para numCPU, podemos pedir ao runtime qual valor é apropriado. A função runtime.NumCPU retorna o número de núcleos de CPU de hardware da máquina, então podemos escrever

var numCPU = runtime.NumCPU()

Há também a função runtime.GOMAXPROCS, que informa (ou define) o número de núcleos, especificado pelo usuário, que um programa Go pode ter rodando simultaneamente. O padrão é o valor de runtime.NumCPU, mas pode ser alterado definindo a variável de ambiente de shell de nome semelhante ou chamando a função com um número positivo. Chamá-la com zero apenas consulta o valor. Portanto, se quisermos respeitar a solicitação de recursos do usuário, devemos escrever

var numCPU = runtime.GOMAXPROCS(0)

Cuidado para não confundir as ideias de concorrência—estruturar um programa como componentes que executam de forma independente—e paralelismo—executar cálculos em paralelo para ganhar eficiência em várias CPUs. Embora os recursos de concorrência de Go possam tornar alguns problemas fáceis de estruturar como cálculos paralelos, Go é uma linguagem concorrente, não uma linguagem paralela, e nem todos os problemas de paralelização se encaixam no modelo de Go. Para uma discussão sobre a distinção, veja a palestra citada neste post do blog.

Um buffer com vazamento

As ferramentas da programação concorrente podem até tornar ideias não concorrentes mais fáceis de expressar. Aqui está um exemplo abstraído de um pacote RPC. A goroutine cliente fica em um laço recebendo dados de alguma fonte, talvez uma rede. Para evitar alocar e liberar buffers, ela mantém uma lista livre e usa um canal com buffer para representá-la. Se o canal estiver vazio, um novo buffer é alocado. Quando o buffer da mensagem estiver pronto, ele é enviado ao servidor por serverChan.

var freeList = make(chan *Buffer, 100)
var serverChan = make(chan *Buffer)

func client() {
    for {
        var b *Buffer
        // Grab a buffer if available; allocate if not.
        select {
        case b = <-freeList:
            // Got one; nothing more to do.
        default:
            // None free, so allocate a new one.
            b = new(Buffer)
        }
        load(b)              // Read next message from the net.
        serverChan <- b      // Send to server.
    }
}

O laço do servidor recebe cada mensagem do cliente, a processa e devolve o buffer à lista livre.

func server() {
    for {
        b := <-serverChan    // Wait for work.
        process(b)
        // Reuse buffer if there's room.
        select {
        case freeList <- b:
            // Buffer on free list; nothing more to do.
        default:
            // Free list full, just carry on.
        }
    }
}

O cliente tenta obter um buffer de freeList; se nenhum estiver disponível, ele aloca um novo. O envio do servidor para freeList devolve b à lista livre, a menos que a lista esteja cheia; nesse caso, o buffer é descartado para ser recuperado pelo coletor de lixo. (As cláusulas default nas instruções select são executadas quando nenhum outro caso está pronto, o que significa que os select nunca bloqueiam.) Esta implementação constrói uma lista livre de balde furado em apenas algumas linhas, contando com o canal com buffer e com o coletor de lixo para a contabilidade.

Erros

Rotinas de biblioteca frequentemente precisam devolver algum tipo de indicação de erro para quem chamou. Como mencionado antes, o retorno com múltiplos valores de Go facilita devolver uma descrição detalhada do erro junto com o valor de retorno normal. É um bom estilo usar esse recurso para fornecer informações detalhadas sobre o erro. Por exemplo, como veremos, os.Open não apenas retorna um ponteiro nil em caso de falha; ele também retorna um valor de erro que descreve o que deu errado.

Por convenção, erros têm o tipo error, uma interface embutida simples.

type error interface {
    Error() string
}

Quem escreve a biblioteca é livre para implementar essa interface com um modelo mais rico por trás, tornando possível não apenas ver o erro, mas também fornecer algum contexto. Como mencionado, junto com o valor de retorno habitual *os.File, os.Open também retorna um valor de erro. Se o arquivo for aberto com sucesso, o erro será nil, mas, quando houver um problema, ele conterá um os.PathError:

// PathError records an error and the operation and
// file path that caused it.
type PathError struct {
    Op string    // "open", "unlink", etc.
    Path string  // The associated file.
    Err error    // Returned by the system call.
}

func (e *PathError) Error() string {
    return e.Op + " " + e.Path + ": " + e.Err.Error()
}

O Error de PathError gera uma string como esta:

open /etc/passwx: no such file or directory

Um erro assim, que inclui o nome do arquivo problemático, a operação e o erro do sistema operacional que o disparou, é útil mesmo se impresso longe da chamada que o causou; ele é muito mais informativo do que o simples "no such file or directory".

Quando for viável, as strings de erro devem identificar sua origem, por exemplo com um prefixo que nomeie a operação ou o pacote que gerou o erro. Por exemplo, no pacote image, a representação em string de um erro de decodificação devido a um formato desconhecido é "image: unknown format".

Quem se importa com os detalhes precisos do erro pode usar um switch de tipo ou uma asserção de tipo para procurar erros específicos e extrair detalhes. Para PathErrors, isso pode incluir examinar o campo interno Err em busca de falhas recuperáveis.

for try := 0; try < 2; try++ {
    file, err = os.Create(filename)
    if err == nil {
        return
    }
    if e, ok := err.(*os.PathError); ok && e.Err == syscall.ENOSPC {
        deleteTempFiles()  // Recover some space.
        continue
    }
    return
}

O segundo if aqui é outra asserção de tipo. Se ela falhar, ok será falso, e e será nil. Se der certo, ok será verdadeiro, o que significa que o erro era do tipo *os.PathError, e então e também é, e podemos examiná-lo para obter mais informações sobre o erro.

Panic

A forma habitual de informar um erro a quem chamou é devolver um error como valor de retorno extra. O método canônico Read é um exemplo conhecido; ele devolve uma contagem de bytes e um error. Mas e se o erro for irrecuperável? Às vezes o programa simplesmente não pode continuar.

Para isso, existe a função embutida panic, que, na prática, cria um erro de tempo de execução que interrompe o programa (mas veja a próxima seção). A função recebe um único argumento de tipo arbitrário—frequentemente uma string—para ser impresso quando o programa morre. É também uma forma de indicar que algo impossível aconteceu, como sair de um laço infinito.

// A toy implementation of cube root using Newton's method.
func CubeRoot(x float64) float64 {
    z := x/3   // Arbitrary initial value
    for i := 0; i < 1e6; i++ {
        prevz := z
        z -= (z*z*z-x) / (3*z*z)
        if veryClose(z, prevz) {
            return z
        }
    }
    // A million iterations has not converged; something is wrong.
    panic(fmt.Sprintf("CubeRoot(%g) did not converge", x))
}

Este é apenas um exemplo, mas funções reais de biblioteca devem evitar panic. Se o problema puder ser mascarado ou contornado, é sempre melhor deixar as coisas continuarem rodando do que derrubar o programa inteiro. Um possível contraexemplo é durante a inicialização: se a biblioteca realmente não consegue se configurar, pode ser razoável entrar em pânico, por assim dizer.

var user = os.Getenv("USER")

func init() {
    if user == "" {
        panic("no value for $USER")
    }
}

Recover

Quando panic é chamado, inclusive implicitamente em erros de tempo de execução como indexar um slice fora dos limites ou falhar uma asserção de tipo, a execução da função atual para imediatamente e começa a desenrolar a pilha da goroutine, executando as funções adiadas pelo caminho. Se esse desenrolar chegar ao topo da pilha da goroutine, o programa morre. No entanto, é possível usar a função embutida recover para retomar o controle da goroutine e continuar a execução normal.

Uma chamada a recover interrompe o desenrolar e devolve o argumento passado para panic. Como o único código que roda durante o desenrolar está dentro de funções adiadas, recover só é útil dentro de funções adiadas.

Uma aplicação de recover é encerrar uma goroutine que falhou dentro de um servidor, sem matar as outras goroutines em execução.

func server(workChan <-chan *Work) {
    for work := range workChan {
        go safelyDo(work)
    }
}

func safelyDo(work *Work) {
    defer func() {
        if err := recover(); err != nil {
            log.Println("work failed:", err)
        }
    }()
    do(work)
}

Neste exemplo, se do(work) entrar em pânico, o resultado será registrado e a goroutine vai sair de forma limpa, sem perturbar as outras. Não há necessidade de fazer mais nada no closure adiado; chamar recover resolve a situação por completo.

Como recover sempre devolve nil, a menos que seja chamado diretamente de uma função adiada, código adiado pode chamar rotinas de biblioteca que usam panic e recover internamente sem falhar. Por exemplo, a função adiada em safelyDo pode chamar uma função de log antes de chamar recover, e esse código de log rodaria sem ser afetado pelo estado de pânico.

Com o nosso padrão de recuperação implementado, a função do (e tudo o que ela chama) pode sair de qualquer situação ruim de forma limpa, chamando panic. Podemos usar essa ideia para simplificar o tratamento de erros em software complexo. Vejamos uma versão idealizada de um pacote regexp, que informa erros de análise chamando panic com um tipo de erro local. Aqui estão a definição de Error, um método error e a função Compile.

// Error is the type of a parse error; it satisfies the error interface.
type Error string
func (e Error) Error() string {
    return string(e)
}

// error is a method of *Regexp that reports parsing errors by
// panicking with an Error.
func (regexp *Regexp) error(err string) {
    panic(Error(err))
}

// Compile returns a parsed representation of the regular expression.
func Compile(str string) (regexp *Regexp, err error) {
    regexp = new(Regexp)
    // doParse will panic if there is a parse error.
    defer func() {
        if e := recover(); e != nil {
            regexp = nil    // Clear return value.
            err = e.(Error) // Will re-panic if not a parse error.
        }
    }()
    return regexp.doParse(str), nil
}

Se doParse entrar em pânico, o bloco de recuperação vai definir o valor de retorno como nil—funções adiadas podem modificar valores de retorno nomeados. Em seguida, ele verifica, na atribuição a err, que o problema foi um erro de análise, afirmando que o valor tem o tipo local Error. Se não tiver, a asserção de tipo falha, causando um erro de tempo de execução que continua o desenrolar da pilha como se nada a tivesse interrompido. Essa verificação significa que, se algo inesperado acontecer, como um índice fora dos limites, o código vai falhar, mesmo que estejamos usando panic e recover para tratar erros de análise.

Com o tratamento de erros no lugar, o método error (como é um método vinculado a um tipo, é válido, até natural, que ele tenha o mesmo nome do tipo embutido error) facilita informar erros de análise sem se preocupar em desenrolar a pilha de análise manualmente:

if pos == 0 {
    re.error("'*' illegal at start of expression")
}

Por mais útil que esse padrão seja, ele deve ser usado apenas dentro de um pacote. Parse transforma suas chamadas internas de panic em valores error; ele não expõe os panics ao seu cliente. Essa é uma boa regra a seguir.

A propósito, esse idioma de re-pânico muda o valor do pânico se ocorrer um erro real. No entanto, tanto a falha original quanto a nova serão exibidas no relatório de falha, então a causa raiz do problema continuará visível. Assim, essa abordagem simples de re-pânico costuma ser suficiente—afinal, é uma falha—mas, se você quiser exibir apenas o valor original, pode escrever um pouco mais de código para filtrar problemas inesperados e entrar em pânico de novo com o erro original. Isso fica como exercício para o leitor.

Um servidor web

Vamos terminar com um programa Go completo, um servidor web. Este é, na verdade, uma espécie de re-servidor web. O Google oferece um serviço em chart.apis.google.com que formata automaticamente dados em gráficos e diagramas. É difícil de usar de forma interativa, porém, porque você precisa colocar os dados na URL como uma query. O programa aqui oferece uma interface mais agradável para um tipo de dado: dado um pequeno trecho de texto, ele chama o servidor de gráficos para produzir um código QR, uma matriz de quadrados que codificam o texto. Essa imagem pode ser capturada pela câmera do celular e interpretada como, por exemplo, uma URL, poupando você de digitar a URL no teclado minúsculo do telefone.

Aqui está o programa completo. Uma explicação vem a seguir.

package main

import (
    "flag"
    "html/template"
    "log"
    "net/http"
)

var addr = flag.String("addr", ":1718", "http service address") // Q=17, R=18

var templ = template.Must(template.New("qr").Parse(templateStr))

func main() {
    flag.Parse()
    http.Handle("/", http.HandlerFunc(QR))
    err := http.ListenAndServe(*addr, nil)
    if err != nil {
        log.Fatal("ListenAndServe:", err)
    }
}

func QR(w http.ResponseWriter, req *http.Request) {
    templ.Execute(w, req.FormValue("s"))
}

const templateStr = `
<html>
<head>
<title>QR Link Generator</title>
</head>
<body>
{{if .}}
<img src="http://chart.apis.google.com/chart?chs=300x300&cht=qr&choe=UTF-8&chl={{.}}" />
<br>
{{.}}
<br>
<br>
{{end}}
<form action="/" name=f method="GET">
    <input maxLength=1024 size=70 name=s value="" title="Text to QR Encode">
    <input type=submit value="Show QR" name=qr>
</form>
</body>
</html>
`

As partes até main devem ser fáceis de acompanhar. A única flag define uma porta HTTP padrão para o nosso servidor. A variável de template templ é onde a diversão acontece. Ela monta um template HTML que será executado pelo servidor para exibir a página; mais sobre isso daqui a pouco.

A função main analisa as flags e, usando o mecanismo sobre o qual falamos acima, vincula a função QR ao caminho raiz do servidor. Em seguida, http.ListenAndServe é chamada para iniciar o servidor; ela bloqueia enquanto o servidor roda.

QR apenas recebe a requisição, que contém dados de formulário, e executa o template sobre os dados no valor do formulário chamado s.

O pacote de templates html/template é poderoso; este programa apenas toca em suas capacidades. Em essência, ele reescreve um trecho de texto HTML em tempo real, substituindo elementos derivados de itens de dados passados para templ.Execute, neste caso o valor do formulário. Dentro do texto do template (templateStr), trechos delimitados por chaves duplas denotam ações de template. O trecho de {{if .}} até {{end}} só é executado se o valor do item de dado atual, chamado . (ponto), não for vazio. Ou seja, quando a string está vazia, esse trecho do template é suprimido.

Os dois trechos {{.}} mandam mostrar os dados apresentados ao template—a string de consulta—na página web. O pacote de templates HTML fornece automaticamente o escape apropriado, para que o texto seja seguro para exibir.

O restante da string do template é apenas o HTML a ser mostrado quando a página carrega. Se esta explicação for rápida demais, veja a documentação do pacote de templates para uma discussão mais completa.

E pronto: um servidor web útil em poucas linhas de código, além de um texto HTML guiado por dados. Go é poderoso o suficiente para fazer muita coisa em poucas linhas.