Se você estiver procurando por suporte AIDL, consulte também FMQ com AIDL .
A infraestrutura de chamada de procedimento remoto (RPC) do HIDL usa mecanismos Binder, o que significa que as chamadas envolvem sobrecarga, exigem operações do kernel e podem acionar a ação do agendador. No entanto, para os casos em que os dados devem ser transferidos entre processos com menos sobrecarga e sem envolvimento do kernel, o sistema Fast Message Queue (FMQ) é usado.
O FMQ cria filas de mensagens com as propriedades desejadas. Um objeto MQDescriptorSync
ou MQDescriptorUnsync
pode ser enviado por meio de uma chamada HIDL RPC e usado pelo processo de recebimento para acessar a fila de mensagens.
Filas rápidas de mensagens são suportadas apenas em C++ e em dispositivos com Android 8.0 e superior.
Tipos de MessageQueue
O Android oferece suporte a dois tipos de fila (conhecidos como sabores ):
- As filas não sincronizadas podem estourar e podem ter muitos leitores; cada leitor deve ler os dados a tempo ou perdê-los.
- As filas sincronizadas não podem estourar e podem ter apenas um leitor.
Ambos os tipos de fila não têm permissão para transbordar (a leitura de uma fila vazia falhará) e podem ter apenas um gravador.
não sincronizado
Uma fila não sincronizada tem apenas um gravador, mas pode ter qualquer número de leitores. Há uma posição de gravação para a fila; no entanto, cada leitor acompanha sua própria posição de leitura independente.
As gravações na fila sempre são bem-sucedidas (não são verificadas quanto ao estouro), desde que não sejam maiores que a capacidade da fila configurada (gravações maiores que a capacidade da fila falham imediatamente). Como cada leitor pode ter uma posição de leitura diferente, em vez de esperar que todos os leitores leiam todos os dados, os dados podem cair da fila sempre que novas gravações precisarem de espaço.
Os leitores são responsáveis por recuperar os dados antes que caiam no final da fila. Uma leitura que tenta ler mais dados do que os disponíveis falha imediatamente (se não for bloqueante) ou espera que dados suficientes estejam disponíveis (se for bloqueante). Uma leitura que tenta ler mais dados do que a capacidade da fila sempre falha imediatamente.
Se um leitor falhar em acompanhar o gravador, de modo que a quantidade de dados gravados e ainda não lidos por esse leitor seja maior que a capacidade da fila, a próxima leitura não retornará dados; em vez disso, ele redefine a posição de leitura do leitor para igualar a posição de gravação mais recente e, em seguida, retorna a falha. Se os dados disponíveis para leitura forem verificados após o estouro, mas antes da próxima leitura, ele mostrará mais dados disponíveis para leitura do que a capacidade da fila, indicando que ocorreu um estouro. (Se a fila estourar entre a verificação dos dados disponíveis e a tentativa de ler esses dados, a única indicação de estouro é que a leitura falha.)
Os leitores de uma fila não sincronizada provavelmente não desejam redefinir os ponteiros de leitura e gravação da fila. Portanto, ao criar a fila a partir do descritor, os leitores devem usar um argumento `false` para o parâmetro `resetPointers`.
sincronizado
Uma fila sincronizada tem um gravador e um leitor com uma única posição de gravação e uma única posição de leitura. É impossível gravar mais dados do que a fila tem espaço para ou ler mais dados do que a fila contém atualmente. Dependendo se a função de gravação ou leitura de bloqueio ou não bloqueio é chamada, as tentativas de exceder o espaço ou dados disponíveis retornam falha imediatamente ou bloqueiam até que a operação desejada possa ser concluída. As tentativas de ler ou gravar mais dados do que a capacidade da fila sempre falharão imediatamente.
Configurando um FMQ
Uma fila de mensagens requer vários objetos MessageQueue
: um para ser gravado e um ou mais para serem lidos. Não há configuração explícita de qual objeto é usado para escrita ou leitura; cabe ao usuário garantir que nenhum objeto seja utilizado tanto para leitura quanto para escrita, que haja no máximo um escritor e, para filas sincronizadas, que haja no máximo um leitor.
Criando o primeiro objeto MessageQueue
Uma fila de mensagens é criada e configurada com uma única chamada:
#include <fmq/MessageQueue.h> using android::hardware::kSynchronizedReadWrite; using android::hardware::kUnsynchronizedWrite; using android::hardware::MQDescriptorSync; using android::hardware::MQDescriptorUnsync; using android::hardware::MessageQueue; .... // For a synchronized non-blocking FMQ mFmqSynchronized = new (std::nothrow) MessageQueue<uint16_t, kSynchronizedReadWrite> (kNumElementsInQueue); // For an unsynchronized FMQ that supports blocking mFmqUnsynchronizedBlocking = new (std::nothrow) MessageQueue<uint16_t, kUnsynchronizedWrite> (kNumElementsInQueue, true /* enable blocking operations */);
- O inicializador
MessageQueue<T, flavor>(numElements)
cria e inicializa um objeto que oferece suporte à funcionalidade de fila de mensagens. - O inicializador
MessageQueue<T, flavor>(numElements, configureEventFlagWord)
cria e inicializa um objeto que dá suporte à funcionalidade de fila de mensagens com bloqueio. -
flavor
pode serkSynchronizedReadWrite
para uma fila sincronizada oukUnsynchronizedWrite
para uma fila não sincronizada. -
uint16_t
(neste exemplo) pode ser qualquer tipo definido em HIDL que não envolva buffers aninhados (semstring
ou tiposvec
), manipuladores ou interfaces. -
kNumElementsInQueue
indica o tamanho da fila em número de entradas; ele determina o tamanho do buffer de memória compartilhada que será alocado para a fila.
Criando o segundo objeto MessageQueue
O segundo lado da fila de mensagens é criado usando um objeto MQDescriptor
obtido do primeiro lado. O objeto MQDescriptor
é enviado por meio de uma chamada HIDL ou AIDL RPC para o processo que manterá a segunda extremidade da fila de mensagens. O MQDescriptor
contém informações sobre a fila, incluindo:
- Informações para mapear o buffer e o ponteiro de gravação.
- Informação para mapear o ponteiro de leitura (caso a fila esteja sincronizada).
- Informação para mapear a palavra sinalizadora do evento (caso a fila esteja bloqueando).
- Tipo de objeto (
<T, flavor>
), que inclui o tipo de elementos de fila definido por HIDL e o tipo de fila (sincronizado ou não sincronizado).
O objeto MQDescriptor
pode ser usado para construir um objeto MessageQueue
:
MessageQueue<T, flavor>::MessageQueue(const MQDescriptor<T, flavor>& Desc, bool resetPointers)
O parâmetro resetPointers
indica se as posições de leitura e gravação devem ser redefinidas para 0 ao criar este objeto MessageQueue
. Em uma fila não sincronizada, a posição de leitura (que é local para cada objeto MessageQueue
em filas não sincronizadas) é sempre definida como 0 durante a criação. Normalmente, o MQDescriptor
é inicializado durante a criação do primeiro objeto de fila de mensagens. Para controle extra sobre a memória compartilhada, você pode configurar o MQDescriptor
manualmente ( MQDescriptor
é definido em system/libhidl/base/include/hidl/MQDescriptor.h
) e criar cada objeto MessageQueue
conforme descrito nesta seção.
Bloqueio de filas e sinalizadores de eventos
Por padrão, as filas não suportam leituras/gravações de bloqueio. Existem dois tipos de bloqueio de chamadas de leitura/gravação:
- Forma abreviada , com três parâmetros (ponteiro de dados, número de itens, tempo limite). Oferece suporte ao bloqueio em operações individuais de leitura/gravação em uma única fila. Ao usar esse formulário, a fila manipulará o sinalizador de evento e as máscaras de bits internamente, e o primeiro objeto de fila de mensagens deve ser inicializado com um segundo parâmetro de
true
. Por exemplo:// For an unsynchronized FMQ that supports blocking mFmqUnsynchronizedBlocking = new (std::nothrow) MessageQueue<uint16_t, kUnsynchronizedWrite> (kNumElementsInQueue, true /* enable blocking operations */);
- Formato longo , com seis parâmetros (inclui sinalizador de evento e bitmasks). Oferece suporte ao uso de um objeto
EventFlag
compartilhado entre várias filas e permite especificar as máscaras de bit de notificação a serem usadas. Nesse caso, o sinalizador de evento e as máscaras de bits devem ser fornecidos para cada chamada de leitura e gravação.
Para o formato longo, o EventFlag
pode ser fornecido explicitamente em cada chamada readBlocking()
e writeBlocking()
. Uma das filas pode ser inicializada com um sinalizador de evento interno, que deve ser extraído dos objetos MessageQueue
dessa fila usando getEventFlagWord()
e usado para criar objetos EventFlag
em cada processo para uso com outros FMQs. Como alternativa, os objetos EventFlag
podem ser inicializados com qualquer memória compartilhada adequada.
Em geral, cada fila deve usar apenas um bloqueio sem bloqueio, bloqueio de formato curto ou bloqueio de formato longo. Não é um erro misturá-los, mas é necessária uma programação cuidadosa para obter o resultado desejado.
Usando o MessageQueue
A API pública do objeto MessageQueue
é:
size_t availableToWrite() // Space available (number of elements). size_t availableToRead() // Number of elements available. size_t getQuantumSize() // Size of type T in bytes. size_t getQuantumCount() // Number of items of type T that fit in the FMQ. bool isValid() // Whether the FMQ is configured correctly. const MQDescriptor<T, flavor>* getDesc() // Return info to send to other process. bool write(const T* data) // Write one T to FMQ; true if successful. bool write(const T* data, size_t count) // Write count T's; no partial writes. bool read(T* data); // read one T from FMQ; true if successful. bool read(T* data, size_t count); // Read count T's; no partial reads. bool writeBlocking(const T* data, size_t count, int64_t timeOutNanos = 0); bool readBlocking(T* data, size_t count, int64_t timeOutNanos = 0); // Allows multiple queues to share a single event flag word std::atomic<uint32_t>* getEventFlagWord(); bool writeBlocking(const T* data, size_t count, uint32_t readNotification, uint32_t writeNotification, int64_t timeOutNanos = 0, android::hardware::EventFlag* evFlag = nullptr); // Blocking write operation for count Ts. bool readBlocking(T* data, size_t count, uint32_t readNotification, uint32_t writeNotification, int64_t timeOutNanos = 0, android::hardware::EventFlag* evFlag = nullptr) // Blocking read operation for count Ts; //APIs to allow zero copy read/write operations bool beginWrite(size_t nMessages, MemTransaction* memTx) const; bool commitWrite(size_t nMessages); bool beginRead(size_t nMessages, MemTransaction* memTx) const; bool commitRead(size_t nMessages);
availableToWrite()
e availableToRead()
podem ser usados para determinar quantos dados podem ser transferidos em uma única operação. Em uma fila não sincronizada:
-
availableToWrite()
sempre retorna a capacidade da fila. - Cada leitor tem sua própria posição de leitura e faz seu próprio cálculo para
availableToRead()
. - Do ponto de vista de um leitor lento, a fila pode transbordar; isso pode fazer com que
availableToRead()
retorne um valor maior que o tamanho da fila. A primeira leitura após um estouro falhará e resultará na posição de leitura desse leitor sendo definida igual ao ponteiro de gravação atual, quer o estouro tenha sido relatado ou não por meio deavailableToRead()
.
Os métodos read()
e write()
retornam true
se todos os dados solicitados puderem (e foram) transferidos para/da fila. Esses métodos não bloqueiam; eles têm sucesso (e retornam true
) ou retornam falha ( false
) imediatamente.
Os métodos readBlocking()
e writeBlocking()
esperam até que a operação solicitada possa ser concluída, ou até que o tempo limite seja esgotado (um valor de timeOutNanos
igual a 0 significa que nunca atinge o tempo limite).
As operações de bloqueio são implementadas usando uma palavra sinalizadora de evento. Por padrão, cada fila cria e usa sua própria palavra sinalizadora para suportar a forma abreviada de readBlocking()
e writeBlocking()
. É possível que várias filas compartilhem uma única palavra, de modo que um processo possa aguardar gravações ou leituras em qualquer uma das filas. Um ponteiro para a palavra sinalizadora de evento de uma fila pode ser obtido chamando getEventFlagWord()
, e esse ponteiro (ou qualquer ponteiro para um local de memória compartilhada adequado) pode ser usado para criar um objeto EventFlag
para passar para a forma longa de readBlocking()
e writeBlocking()
para uma fila diferente. Os parâmetros readNotification
e writeNotification
informam quais bits no sinalizador de evento devem ser usados para sinalizar leituras e gravações nessa fila. readNotification
e writeNotification
são máscaras de bits de 32 bits.
readBlocking()
espera nos bits writeNotification
; se esse parâmetro for 0, a chamada sempre falhará. Se o valor readNotification
for 0, a chamada não falhará, mas uma leitura bem-sucedida não definirá nenhum bit de notificação. Em uma fila sincronizada, isso significaria que a chamada writeBlocking()
correspondente nunca será ativada, a menos que o bit seja definido em outro lugar. Em uma fila não sincronizada, writeBlocking()
não esperará (ainda deve ser usado para definir o bit de notificação de gravação) e é apropriado para leituras não definir nenhum bit de notificação. Da mesma forma, writeblocking()
falhará se readNotification
for 0 e uma gravação bem-sucedida definir os bits writeNotification
especificados.
Para aguardar várias filas de uma vez, use o método wait()
de um objeto EventFlag
para aguardar uma máscara de bits de notificações. O método wait()
retorna uma palavra de status com os bits que causaram o conjunto de ativação. Essas informações são usadas para verificar se a fila correspondente tem espaço ou dados suficientes para a operação de gravação/leitura desejada e executar uma write()
/ read()
sem bloqueio. Para obter uma notificação pós-operação, use outra chamada para o método wake()
do EventFlag
. Para obter uma definição da abstração EventFlag
, consulte system/libfmq/include/fmq/EventFlag.h
.
Zero operações de cópia
As APIs read
/ write
/ readBlocking
/ writeBlocking()
usam um ponteiro para um buffer de entrada/saída como um argumento e usam chamadas memcpy()
internamente para copiar dados entre o mesmo e o buffer de anel FMQ. Para melhorar o desempenho, o Android 8.0 e superior incluem um conjunto de APIs que fornecem acesso de ponteiro direto ao buffer de anel, eliminando a necessidade de usar chamadas memcpy
.
Use as seguintes APIs públicas para operações FMQ de cópia zero:
bool beginWrite(size_t nMessages, MemTransaction* memTx) const; bool commitWrite(size_t nMessages); bool beginRead(size_t nMessages, MemTransaction* memTx) const; bool commitRead(size_t nMessages);
- O método
beginWrite
fornece ponteiros de base para o buffer de anel FMQ. Depois que os dados forem gravados, confirme-os usandocommitWrite()
. Os métodosbeginRead
/commitRead
agem da mesma forma. - Os métodos
beginRead
/Write
recebem como entrada o número de mensagens a serem lidas/escritas e retornam um valor booleano indicando se a leitura/escrita é possível. Se a leitura ou gravação for possível, a estruturamemTx
será preenchida com ponteiros de base que podem ser usados para acesso de ponteiro direto na memória compartilhada do buffer de anel. - A estrutura
MemRegion
contém detalhes sobre um bloco de memória, incluindo o ponteiro base (endereço base do bloco de memória) e o comprimento em termos deT
(comprimento do bloco de memória em termos do tipo definido por HIDL da fila de mensagens). - O struct
MemTransaction
contém dois structsMemRegion
, ofirst
esecond
pois uma leitura ou gravação no buffer de anel pode exigir um retorno ao início da fila. Isso significaria que dois ponteiros base são necessários para ler/escrever dados no buffer de anel FMQ.
Para obter o endereço base e o comprimento de uma estrutura MemRegion
:
T* getAddress(); // gets the base address size_t getLength(); // gets the length of the memory region in terms of T size_t getLengthInBytes(); // gets the length of the memory region in bytes
Para obter referências ao primeiro e ao segundo MemRegion
s em um objeto MemTransaction
:
const MemRegion& getFirstRegion(); // get a reference to the first MemRegion const MemRegion& getSecondRegion(); // get a reference to the second MemRegion
Exemplo de gravação no FMQ usando APIs de cópia zero:
MessageQueueSync::MemTransaction tx; if (mQueue->beginRead(dataLen, &tx)) { auto first = tx.getFirstRegion(); auto second = tx.getSecondRegion(); foo(first.getAddress(), first.getLength()); // method that performs the data write foo(second.getAddress(), second.getLength()); // method that performs the data write if(commitWrite(dataLen) == false) { // report error } } else { // report error }
Os seguintes métodos auxiliares também fazem parte de MemTransaction
:
-
T* getSlot(size_t idx);
Retorna um ponteiro para o slotidx
dentro dasMemRegions
que fazem parte deste objetoMemTransaction
. Se o objetoMemTransaction
estiver representando as regiões de memória para ler/gravar N itens do tipo T, o intervalo válido deidx
estará entre 0 e N-1. -
bool copyTo(const T* data, size_t startIdx, size_t nMessages = 1);
Grave itensnMessages
do tipo T nas regiões de memória descritas pelo objeto, começando pelo índicestartIdx
. Este método usamemcpy()
e não deve ser usado para uma operação de cópia zero. Se o objetoMemTransaction
representa memória para ler/gravar N itens do tipo T, então o intervalo válido deidx
está entre 0 e N-1. -
bool copyFrom(T* data, size_t startIdx, size_t nMessages = 1);
Método auxiliar para ler itensnMessages
do tipo T das regiões de memória descritas pelo objeto a partir destartIdx
. Este método usamemcpy()
e não deve ser usado para uma operação de cópia zero.
Enviando a fila por HIDL
Do lado da criação:
- Crie um objeto de fila de mensagens conforme descrito acima.
- Verifique se o objeto é válido com
isValid()
. - Se você estiver esperando em várias filas passando um
EventFlag
para o formato longo dereadBlocking()
/writeBlocking()
, você pode extrair o ponteiro do sinalizador de evento (usandogetEventFlagWord()
) de um objetoMessageQueue
que foi inicializado para criar o sinalizador, e use esse sinalizador para criar o objetoEventFlag
necessário. - Use o método
MessageQueue
getDesc()
para obter um objeto descritor. - No arquivo
.hal
, dê ao método um parâmetro do tipofmq_sync
ou fmq_unsync
onde T
é um tipo definido por HIDL adequado. Use isso para enviar o objeto retornado porgetDesc()
para o processo receptor.
Do lado receptor:
- Use o objeto descritor para criar um objeto
MessageQueue
. Certifique-se de usar o mesmo tipo de fila e tipo de dados, ou o modelo falhará ao compilar. - Se você extraiu um sinalizador de evento, extraia o sinalizador do objeto
MessageQueue
correspondente no processo de recebimento. - Use o objeto
MessageQueue
para transferir dados.