En esta página

QGrpcHttp2Channel Class

La clase QGrpcHttp2Channel proporciona una capa de transporte HTTP/2 para gRPC™ la comunicación. Más información...

Encabezado: #include <QGrpcHttp2Channel>
CMake: find_package(Qt6 REQUIRED COMPONENTS Grpc)
target_link_libraries(mytarget PRIVATE Qt6::Grpc)
Desde: Qt 6.5
En QML: GrpcHttp2Channel
Heredan de: QAbstractGrpcChannel

Funciones públicas

QGrpcHttp2Channel(const QUrl &hostUri)
QGrpcHttp2Channel(const QUrl &hostUri, const QGrpcChannelOptions &options)
virtual ~QGrpcHttp2Channel() override
QUrl hostUri() const

Descripción detallada

La clase QGrpcHttp2Channel implementa ` QAbstractGrpcChannel`, lo que permite gRPC™ la comunicación a través de la estructura de tramas de HTTP/2.

HTTP/2 presenta varias ventajas con respecto a su predecesor, HTTP/1.1, lo que hace que QGrpcHttp2Channel sea ideal para aplicaciones en tiempo real de alto rendimiento que requieren una comunicación eficiente, sin sacrificar la seguridad ni la fiabilidad, mediante el uso de conexiones TCP multiplexadas.

El canal se puede personalizar con soporte SSL, un ` serializationFormat` personalizado u otras opciones, creándolo con un ` QGrpcChannelOptions ` que contenga las personalizaciones necesarias.

Nota: QGrpcChannelOptions::filterServerMetadata está habilitado de forma predeterminada.

Esquema de transporte

La implementación de QGrpcHttp2Channel da preferencia a distintos métodos de transporte en función de los valores proporcionados en hostUri, scheme y las opciones. Se aplican los siguientes criterios:

EsquemaDescripciónPuerto por defectoRequisitosEjemplo
httpHTTP/2 sin cifrar sobre TCP80Ningunohttp://localhost
httpsHTTP/2 cifrado con TLS sobre TCP443QSslSocket compatible con (esquema O sslConfiguration)https://localhost
unixSocket de dominio Unix en ruta del sistema de archivos✗QLocalSocket compatible Y esquemaunix:///tmp/grpc.socket
unix-abstractSocket de dominio Unix en un espacio de nombres abstracto✗QLocalSocket Compatible con «AND» y « AbstractNamespace » Compatible con «AND» y «scheme»unix-abstract:app_grpc_channel

Content-Type

El tipo de contenido en gRPC sobre HTTP/2 determina el formato de serialización del mensaje. Debe comenzar por application/grpc y puede incluir un sufijo. El formato sigue este esquema:

"content-type": "application/grpc" [("+proto" / "+json" / {custom})]

Por ejemplo:

  • application/grpc+proto especifica la codificación Protobuf.
  • application/grpc+json especifica la codificación JSON.

El formato de serialización se puede configurar bien especificando el « content-type » dentro de los metadatos, bien estableciendo directamente « serializationFormat ». Por defecto, se utiliza el tipo de contenido « application/grpc ».

Para configurar QGrpcHttp2Channel con el formato de serialización JSON utilizando los metadatos de content-type:

auto jsonChannel = std::make_shared<QGrpcHttp2Channel>(
    QUrl("http://localhost:50051"_L1),
    QGrpcChannelOptions().setMetadata({
        { "content-type"_ba, "application/grpc+json"_ba },
    })
);

Para un serializador personalizado y ` content-type`, puedes establecer directamente el formato de serialización:

class DummySerializer : public QAbstractProtobufSerializer
{
    ...
};
QGrpcSerializationFormat dummyFormat("dummy", std::make_shared<DummySerializer>());
auto dummyChannel = std::make_shared<QGrpcHttp2Channel>(
    QUrl("http://localhost:50051"_L1),
    QGrpcChannelOptions().setSerializationFormat(dummyFormat)
);

Esto utiliza DummySerializer para codificar y descodificar mensajes con el sufijo dummy. Para el transporte HTTP/2, esto da como resultado el tipo de contenido application/grpc+dummy.

Nota: Los serializadorespersonalizados requieren que el servidor admita el formato especificado.

Claves de metadatos reservadas

Los metadatos se transmiten como encabezados HTTP/2: las claves son cadenas ASCII que no distinguen entre mayúsculas y minúsculas, mientras que los valores pueden ser cadenas ASCII o datos binarios. Las siguientes claves están reservadas por HTTP/2 o por el protocolo gRPC y se omiten de los metadatos del usuario al construir la solicitud:

  • Pseudoencabezados de HTTP/2 (cualquier clave que comience por :).
  • Cualquier clave con el prefijo grpc- o qtgrpc-.
  • te, content-type, user-agent.

Un content-type proporcionado por el usuario sigue consultándose durante la construcción del canal para la detección automática del serializador (véase Content-Type); sin embargo, no se reenvía como una entrada de metadatos personalizados.

Para obtener más información sobre los encabezados HTTP/2, véase el RFC 7540, sección 8.1.2.

Ventanas de recepción

El control de flujo de HTTP/2 limita la cantidad de datos que un remitente puede transmitir antes de que el receptor los acuse recibo. El canal comunica al servidor dos de estos límites, las ventanas de recepción:

  • La ventana de flujo limita los datos no confirmados de una sola RPC.
  • La ventana de conexión limita los datos no confirmados combinados de todas las RPC que comparten una misma conexión.

Una ventana limita los datos en tránsito, no el tamaño de una transferencia. Dado que los acuses de recibo requieren un ciclo de ida y vuelta por la red, también limita el rendimiento:

maximum throughput = window / round-trip time

Ambas ventanas se configuran en bytes mediante variables de entorno:

  • QT_GRPC_HTTP2_STREAM_RECEIVE_WINDOW_SIZE para las ventanas de flujo; (por defecto, 4 MiB)
  • QT_GRPC_HTTP2_CONNECTION_RECEIVE_WINDOW_SIZE para la ventana de conexión; (por defecto, cuatro veces la ventana de flujo, 16 MiB)

Si solo se establece QT_GRPC_HTTP2_STREAM_RECEIVE_WINDOW_SIZE, la ventana de conexión se escala automáticamente a cuatro veces la ventana de flujo. Establece QT_GRPC_HTTP2_CONNECTION_RECEIVE_WINDOW_SIZE explícitamente para utilizar una proporción diferente.

Los valores por defecto saturan las redes locales y la mayoría de las rutas de Internet. Resultan insuficientes en enlaces rápidos con tiempos de ida y vuelta largos. Por ejemplo, una aplicación recibe mensajes de gran tamaño desde un servidor lejano:

link: 1 Gbit/s (125 MB/s), 100 ms round-trip time

El servidor envía una ventana de flujo de datos y, a continuación, espera un tiempo de ida y vuelta para recibir el acuse de recibo. Con la ventana predeterminada, envía como máximo 4 MiB cada 100 ms:

4 MiB / 0.1 s = 42 MB/s, 34% of the 125 MB/s the link carries

Para saturar el enlace, la ventana debe contener todo lo que el enlace envía durante un ciclo de ida y vuelta, es decir, el producto ancho de banda-retardo (BDP) del enlace:

BDP = 125 MB/s x 0.1 s = 12.5 MB

QT_GRPC_HTTP2_STREAM_RECEIVE_WINDOW_SIZE=12500000
12.5 MB / 0.1 s = 125 MB/s, the link is saturated

Las RPC simultáneas comparten una única ventana de recepción de la conexión. Siempre que cada flujo se lea de forma continua, el total de datos en tránsito permanece limitado por el BDP. Sin embargo, si no se lee un flujo, sus datos almacenados en el búfer consumen parte de la ventana de conexión compartida y pueden bloquear otros flujos. Una buena regla general es dimensionar la ventana de conexión en función de la suma de todas las ventanas de flujos activas simultáneamente. Para ocho transferencias paralelas en el enlace anterior:

QT_GRPC_HTTP2_STREAM_RECEIVE_WINDOW_SIZE=12500000       (12.5 MB = BDP)
QT_GRPC_HTTP2_CONNECTION_RECEIVE_WINDOW_SIZE=100000000  (8 x 12.5 MB)

Cada RPC puede utilizar los 125 MB/s completos cuando es la única transferencia activa. Con ocho RPC simultáneos, comparten el enlace a aproximadamente 15 MB/s cada uno. En el peor de los casos, si la aplicación deja de leer de todos los flujos, el canal puede almacenar en el búfer hasta 100 MB de datos.

Como alternativa, dimensiona las ventanas de flujo de modo que, en conjunto, quepan dentro de una ventana de conexión igual al BDP. Esto limita la cantidad máxima de datos almacenados en el búfer, pero restringe cada RPC a la parte que se le ha asignado, incluso cuando se transfiere en solitario:

QT_GRPC_HTTP2_STREAM_RECEIVE_WINDOW_SIZE=1562500        (12.5 MB / 8)
QT_GRPC_HTTP2_CONNECTION_RECEIVE_WINDOW_SIZE=12500000   (= BDP)

Cada RPC está limitado a aproximadamente 15 MB/s, tanto si se transfiere solo como junto con otros siete. La ventaja es que el canal nunca almacena en el búfer más de unos 12,5 MB de datos sin leer.

Utilice ventanas de flujo de tamaño completo cuando sea más importante minimizar la latencia de transferencia que el uso de memoria. Utilice ventanas de flujo más pequeñas cuando la prioridad sea limitar el consumo de memoria. En cualquier caso, mantenga la ventana de conexión lo suficientemente grande como para albergar varias ventanas de flujo; de lo contrario, un solo flujo sin leer puede agotar la ventana de conexión compartida y bloquear todas las demás RPC.

Ambas ventanas admiten valores de hasta 2147483647 bytes. La ventana de flujo tiene un límite mínimo de 1024 bytes, lo que permite a los receptores con limitaciones de memoria restringir el almacenamiento en búfer por flujo; la ventana de conexión tiene un límite mínimo de 65535 bytes, que es la ventana inicial del protocolo.

Valores por defecto de las variables de entorno

Algunos ajustes de los canales se pueden configurar mediante variables de entorno. Estas se evalúan cuando se crea cada canal. Si no se ha establecido una variable de entorno, se utiliza el valor predeterminado integrado.

Variable de entornoOpciónValor predeterminado
QT_GRPC_MAXIMUM_RECEIVE_MESSAGE_SIZEmaximumReceiveMessageSize4 MiB (4 194 304 bytes)
QT_GRPC_MAXIMUM_METADATA_SIZENinguno16 KiB (16 384 bytes)
QT_GRPC_INITIAL_RECONNECT_BACKOFF_MSNinguna1 s (1 000 ms)
QT_GRPC_MAXIMUM_RECONNECT_BACKOFF_MSNinguno120 s (120 000 ms)
QT_GRPC_CONNECT_TIMEOUT_MSNinguno20 s (20 000 ms)
QT_GRPC_HTTP2_STREAM_RECEIVE_WINDOW_SIZENinguno4 MiB (4 194 304 bytes)
QT_GRPC_HTTP2_CONNECTION_RECEIVE_WINDOW_SIZENinguno16 MiB (16 777 216 bytes)

Véase también QAbstractGrpcChannel, QGrpcChannelOptions y QGrpcSerializationFormat.

Documentación de las funciones de miembro

[explicit] QGrpcHttp2Channel::QGrpcHttp2Channel(const QUrl &hostUri)

Crea un objeto `QGrpcHttp2Channel` con ` hostUri`. Para obtener más información, consulta la sección « Transportation scheme ».

[explicit] QGrpcHttp2Channel::QGrpcHttp2Channel(const QUrl &hostUri, const QGrpcChannelOptions &options)

Crea un objeto `QGrpcHttp2Channel` con ` hostUri ` y ` options`. Para obtener más información, consulta la sección « Transportation scheme ».

[override virtual noexcept] QGrpcHttp2Channel::~QGrpcHttp2Channel()

Elimina el objeto « QGrpcHttp2Channel ».

QUrl QGrpcHttp2Channel::hostUri() const

Devuelve el URI del host de este canal.

El URI se normaliza según Transportation scheme: el esquema puede ajustarse y puede completarse con un puerto predeterminado. Al volver a enviar el URI devuelto a QGrpcHttp2Channel, se seleccionará la misma configuración de transporte.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.