En esta página

Bloqueo de remitentes

Muestra cómo utilizar la API síncrona de QSerialPort en un hilo de trabajo.

«Blocking Sender» muestra cómo crear una aplicación para una interfaz serie utilizando la API síncrona de QSerialPort en un hilo de trabajo.

Bloqueo del emisor del Qt Serial Port

QSerialPort Admite dos alternativas de programación:

  • La alternativa asíncrona (no bloqueante). Las operaciones se programan y se ejecutan cuando el control vuelve al bucle de eventos de Qt. La clase ` QSerialPort ` emite una señal cuando finaliza la operación. Por ejemplo, el método ` write()` devuelve el control inmediatamente. Cuando los datos se envían al puerto serie, la clase ` QSerialPort ` emite la señal ` bytesWritten()`.
  • La alternativa síncrona (bloqueante). En aplicaciones sin interfaz gráfica y multihilo, se puede llamar al método `wait` (en este caso, ` waitForReadyRead()`) para suspender el hilo que realiza la llamada hasta que la operación haya finalizado.

En este ejemplo se muestra la alternativa síncrona. El ejemplo «Terminal» ilustra la alternativa asíncrona.

El objetivo de este ejemplo es mostrar cómo simplificar el código de programación en serie sin perder la capacidad de respuesta de la interfaz de usuario. La API de programación en serie bloqueante suele dar lugar a un código más sencillo, pero solo debe utilizarse en subprocesos que no sean de la interfaz gráfica de usuario para mantener la capacidad de respuesta de esta.

Esta aplicación es el emisor, que muestra cómo funciona junto con la aplicación receptora del ejemplo «Receptor bloqueante».

La aplicación emisora inicia la solicitud de transferencia a través del puerto serie hacia la aplicación receptora y espera la respuesta.

class SenderThread : public QThread
{
    Q_OBJECT

public:
    explicit SenderThread(QObject *parent = nullptr);
    ~SenderThread();

    void transaction(const QString &portName, int waitTimeout, const QString &request);

signals:
    void response(const QString &s);
    void error(const QString &s);
    void timeout(const QString &s);

private:
    void run() override;

    QString m_portName;
    QString m_request;
    int m_waitTimeout = 0;
    QMutex m_mutex;
    QWaitCondition m_cond;
    bool m_quit = false;
};

`SenderThread` es una subclase de ` QThread ` que proporciona una API para programar solicitudes al receptor. Esta clase proporciona señales para responder y notificar errores. Se puede llamar al método `transaction()` para iniciar una nueva transacción del emisor con la solicitud deseada. El resultado se obtiene a través de la señal `response()`. En caso de que surja algún problema, se emite la señal `error()` o `timeout()`.

Tenga en cuenta que el método `transaction()` se invoca en el hilo principal, pero la solicitud se envía en el hilo `SenderThread`. Los miembros de datos de `SenderThread` se leen y escriben de forma concurrente en diferentes hilos, por lo que se utiliza la clase ` QMutex ` para sincronizar el acceso.

void SenderThread::transaction(const QString &portName, int waitTimeout, const QString &request)
{
    const QMutexLocker locker(&m_mutex);
    m_portName = portName;
    m_waitTimeout = waitTimeout;
    m_request = request;
    if (!isRunning())
        start();
    else
        m_cond.wakeOne();
}

El método `transaction()` almacena el nombre del puerto serie, el tiempo de espera y los datos de la solicitud. El mutex se puede bloquear con ` QMutexLocker ` para proteger estos datos. A continuación, se puede iniciar el hilo, a menos que ya se esté ejecutando. El método ` wakeOne()` se analiza más adelante.

void SenderThread::run()
{
    bool currentPortNameChanged = false;

    m_mutex.lock();
    QString currentPortName;
    if (currentPortName != m_portName) {
        currentPortName = m_portName;
        currentPortNameChanged = true;
    }

    int currentWaitTimeout = m_waitTimeout;
    QString currentRequest = m_request;
    m_mutex.unlock();

En la función `run()`, lo primero es bloquear el objeto ` QMutex ` y, a continuación, obtener el nombre del puerto serie, el tiempo de espera y los datos de la solicitud utilizando los datos de los miembros. Una vez hecho esto, se libera el bloqueo de ` QMutex `.

Bajo ninguna circunstancia debe llamarse al método ` transaction() ` simultáneamente con un proceso que esté obteniendo los datos. Ten en cuenta que, aunque la clase ` QString ` es reentrante, no es segura para subprocesos. Por lo tanto, no se recomienda leer el nombre del puerto serie en un subproceso de solicitud y obtener el tiempo de espera o los datos de la solicitud en otro subproceso. La clase `SenderThread` solo puede gestionar una solicitud a la vez.

El objeto ` QSerialPort ` se construye en la pila en el método `run()` antes de entrar en el bucle:

    QSerialPort serial;

    if (currentPortName.isEmpty()) {
        emit error(tr("No port name specified"));
        return;
    }

    while (!m_quit) {

Esto permite crear un objeto mientras se ejecuta el bucle. También significa que todos los métodos del objeto se ejecutan dentro del ámbito del método run().

Dentro del bucle se comprueba si ha cambiado o no el nombre del puerto serie de la transacción actual. Si ha cambiado, el puerto serie se vuelve a abrir y, a continuación, se reconfigura.

        if (currentPortNameChanged) {
            serial.close();
            serial.setPortName(currentPortName);

            if (!serial.open(QIODevice::ReadWrite)) {
                emit error(tr("Can't open %1, error code %2")
                           .arg(m_portName).arg(serial.error()));
                return;
            }
        }

El bucle seguirá solicitando datos, escribiendo en el puerto serie y esperando hasta que se hayan transferido todos los datos.

        // write request
        const QByteArray requestData = currentRequest.toUtf8();
        serial.write(requestData);
        if (serial.waitForBytesWritten(m_waitTimeout)) {

Advertencia: Al igual que en la transferencia bloqueante, se debe utilizar el método ` waitForBytesWritten()` después de cada llamada al método ` write `. De este modo, se procesarán todas las rutinas de E/S en lugar de que lo haga el bucle de eventos de Qt.

Se emite la señal timeout() si se produce un error de tiempo de espera durante la transferencia de datos.

        } else {
            emit timeout(tr("Wait write request timeout %1")
                         .arg(QTime::currentTime().toString()));
        }

Hay un periodo de espera para recibir la respuesta tras una solicitud correcta, y luego se vuelve a leer.

            // read response
            if (serial.waitForReadyRead(currentWaitTimeout)) {
                QByteArray responseData = serial.readAll();
                while (serial.waitForReadyRead(10))
                    responseData += serial.readAll();

                const QString response = QString::fromUtf8(responseData);
                emit this->response(response);

Advertencia: En cuanto a la alternativa bloqueante, se debe utilizar el método waitForReadyRead() antes de cada llamada a read(). De este modo, se procesarán todas las rutinas de E/S en lugar de que lo haga el bucle de eventos de Qt.

Se emite la señal «timeout()» si se produce un error de tiempo de espera al recibir datos.

            } else {
                emit timeout(tr("Wait read response timeout %1")
                             .arg(QTime::currentTime().toString()));
            }

Cuando una transacción se ha completado con éxito, la señal response() contiene los datos recibidos de la aplicación receptora:

                emit this->response(response);

A continuación, el hilo entra en estado de suspensión hasta que aparece la siguiente transacción. Al reactivarse, el hilo lee los nuevos datos utilizando los miembros y ejecuta el bucle desde el principio.

        m_mutex.lock();
        m_cond.wait(&m_mutex);
        if (currentPortName != m_portName) {
            currentPortName = m_portName;
            currentPortNameChanged = true;
        } else {
            currentPortNameChanged = false;
        }
        currentWaitTimeout = m_waitTimeout;
        currentRequest = m_request;
        m_mutex.unlock();
    }

Ejecución del ejemplo

Puedes ejecutar el ejemplo desde:

Proyecto de ejemplo en code.qt.io

Véase también «Terminal serie » y «Receptor bloqueante».

© 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.