Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -474,6 +474,16 @@ be lost, and the `Status` a part below the facade passes on. A setter's `Status`
to tell, and the examples do. Where the library drops a marked result on purpose, it hands it to
`Discard()` with the reason beside it.

The host code marks alike what it computes or finds, as `ControlCommand::MakeText()` or
`SimulatorWebSocket::EncodeFrame()`, and leaves unmarked what only says whether an action
worked, as `Send()` or `Begin()`. It drops no result without `Discard()` and its reason, marked
or not, a system call's as well (`close()`, `setsockopt()`, `avr_ioctl()`), and handles one
whose failure matters instead: a socket that still blocks is closed, not polled. A result is a
value that tells the caller something, success, a count, a place or whether something changed;
a reference to the object itself, as `std::string::append()` and `std::ostream::flush()` return,
or a handle to what was just added, as `wxSizer::Add()` returns, is none, as the call returns
it only so that calls can be chained.

The texts lie in a table in `PROGMEM`, not behind a `switch`: avr-gcc turns a `switch` that
returns a constant per case into a table in `.rodata`, which the Uno copies into RAM, as it does
with every constant not marked `PROGMEM`.
Expand Down
12 changes: 11 additions & 1 deletion OIL.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Status: `open`, `in progress`, `done`, `dropped` (with the reason in the item).
| 38 | Results that must not be ignored | 36 | done | #94 |
| 39 | MC/DC coverage | 34 | done | #95, #96 |
| 40 | Braced initialization checked | 34 | done | #93 |
| 41 | The template's rules that review checks | 36 | in progress | #99, #100, #101, #102, #104, #105, #106, #107, #113, #115, #116, #117, #118, #121, #122, #124, #125, #126 |
| 41 | The template's rules that review checks | 36 | in progress | #99, #100, #101, #102, #104, #105, #106, #107, #113, #115, #116, #117, #118, #121, #122, #124, #125, #126, #127 |
| 42 | A newer avr-gcc as a cross-check | 41 | done | |
| 43 | Bit operations in one class, from the template | 41 | done | #109 |

Expand Down Expand Up @@ -1180,6 +1180,16 @@ calls, as what a port has read, the index into the command line and the labels a
`DocuPictures` draws on are references. `SimulatorRun::SetUp()` keeps its two references, as it
sets up the objects the tick reaches through a plain function pointer.

As built for FN-10 in the host code: no result is dropped without `Discard()` and its reason,
a system call's included. Where a failure matters it is handled instead: a socket that still
blocks after `SetNonBlocking()`, or that would wait without end for a request, is closed rather
than polled; `avr_init()` that fails fails the load; a matrix of `DocuPictures` that does not
start fails the run; and the control program logs a window without a timer. What only says
whether something changed, as wxWidgets' `Enable()`, goes to `Discard()` as well, and so does
`close()`, through `SimulatorSocket::Close()` in the simulator. What the host code computes or
finds is `MAXMATRIX_NODISCARD` now, some thirty functions. A reference to the object itself or a
handle to what was just added is no result, AGENTS.md says why.

### 42 A newer avr-gcc as a cross-check

`max_matrix::Byte` (41) made the examples 30 to 50 bytes of flash larger on the Uno at first,
Expand Down
20 changes: 11 additions & 9 deletions control/ControlCommand.h
Original file line number Diff line number Diff line change
Expand Up @@ -58,23 +58,24 @@ class ControlCommand {
* \param[in] shift True to shift it in, false to show it at once.
* \return The line.
*/
static std::string MakeText(std::string const& text, bool shift);
MAXMATRIX_NODISCARD static std::string MakeText(std::string const& text,
bool shift);

/*!
* \brief Makes the line that sets the brightness.
*
* \param[in] intensity The brightness, 0 to 15.
* \return The line.
*/
static std::string MakeIntensity(uint8_t intensity);
MAXMATRIX_NODISCARD static std::string MakeIntensity(uint8_t intensity);

/*!
* \brief Makes the line that sets how fast a text shifts.
*
* \param[in] milliseconds The time per column.
* \return The line.
*/
static std::string MakeSpeed(uint16_t milliseconds);
MAXMATRIX_NODISCARD static std::string MakeSpeed(uint16_t milliseconds);

/*!
* \brief Makes the line that sets the empty columns between the chars of a
Expand All @@ -83,7 +84,7 @@ class ControlCommand {
* \param[in] columns The columns.
* \return The line.
*/
static std::string MakeSpace(uint8_t columns);
MAXMATRIX_NODISCARD static std::string MakeSpace(uint8_t columns);

/*!
* \brief Makes the line that lights a dot or turns it off.
Expand All @@ -93,21 +94,22 @@ class ControlCommand {
* \param[in] lit True to light it, false to turn it off.
* \return The line.
*/
static std::string MakeDot(uint8_t column, uint8_t row, bool lit);
MAXMATRIX_NODISCARD static std::string MakeDot(uint8_t column, uint8_t row,
bool lit);

/*!
* \brief Makes the line that turns every LED off.
*
* \return The line.
*/
static std::string MakeClear();
MAXMATRIX_NODISCARD static std::string MakeClear();

/*!
* \brief Makes the line that asks what the matrix shows.
*
* \return The line.
*/
static std::string MakePicture();
MAXMATRIX_NODISCARD static std::string MakePicture();

/*!
* \brief Decodes the answer to `picture` into the columns of the panel.
Expand All @@ -128,7 +130,7 @@ class ControlCommand {
* \return True if it fits into the board's line buffer and holds no line
* break.
*/
static bool Fits(std::string const& line);
MAXMATRIX_NODISCARD static bool Fits(std::string const& line);

/*!
* \brief Returns how many bytes `line` may still grow by before SerialControl
Expand All @@ -138,7 +140,7 @@ class ControlCommand {
* \return The bytes left in the board's line buffer, negative by as many
* bytes as the line is too long.
*/
static int32_t GetBytesLeft(std::string const& line);
MAXMATRIX_NODISCARD static int32_t GetBytesLeft(std::string const& line);
};

#endif // MAXMATRIX_CONTROL_CONTROLCOMMAND_H_
7 changes: 4 additions & 3 deletions control/ControlDotPanel.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
#include <vector>

#include "ControlCommand.h"
#include "MaxMatrixAttributes.h"
#include "MaxMatrixConfig.h"
#include "Utility/Bit.h"

Expand Down Expand Up @@ -57,9 +58,9 @@ ControlDotPanel::ControlDotPanel(
wxCoord const height{(max_matrix::kRowNumberOfModule * kCell) +
(2 * kMargin)};

// the background is painted whole by OnPaint(), which the buffered DC needs
// to know
SetBackgroundStyle(wxBG_STYLE_PAINT);
// The background is painted whole by OnPaint(), which the buffered DC needs
// to know; the style fails only for a transparent background a system lacks.
max_matrix::Discard(SetBackgroundStyle(wxBG_STYLE_PAINT));
SetMinSize(FromDIP(wxSize(width, height)));
Bind(wxEVT_PAINT, &ControlDotPanel::OnPaint, this);
Bind(wxEVT_LEFT_DOWN, &ControlDotPanel::OnLeftDown, this);
Expand Down
2 changes: 1 addition & 1 deletion control/ControlLink.h
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ class ControlLink {
bool picture_timed_{false};
uint32_t picture_asked_at_{0};

bool Take(std::string const& line);
MAXMATRIX_NODISCARD bool Take(std::string const& line);

public:
/*!
Expand Down
53 changes: 35 additions & 18 deletions control/ControlSerialPort.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@

#include "ControlSerialPort.h"
#include "ControlStream.h"
#include "MaxMatrixAttributes.h"
#include "Utility/Bit.h"

namespace {
Expand Down Expand Up @@ -157,7 +158,11 @@ bool ControlSerialPort::Read(std::string& data) {
}

void ControlSerialPort::Close() {
if (handle_ != INVALID_HANDLE_VALUE) CloseHandle(handle_);
if (handle_ != INVALID_HANDLE_VALUE) {
// The handle is gone even when it reports an error, and there is nothing
// to try again.
max_matrix::Discard(CloseHandle(handle_));
}
handle_ = INVALID_HANDLE_VALUE;
}

Expand All @@ -176,44 +181,54 @@ ControlSerialPort::~ControlSerialPort() { Close(); }
* it.
*/
bool ControlSerialPort::Open(std::string const& name, uint32_t baud_rate) {
termios settings{};

Close();
if (!IsBaudRate(baud_rate)) {
return false;
}
/* read and write, not as the terminal that controls this process, and
* without waiting for the modem lines */
constexpr int kOpenFlags{O_RDWR | O_NOCTTY | O_NONBLOCK};
/* the modem lines ignored, and receiving on */
constexpr tcflag_t kLocalReceive{CLOCAL | CREAD};
/* two stop bits and the hardware handshake, both off for SerialControl */
constexpr tcflag_t kTwoStopsHandshake{CSTOPB | CRTSCTS};

// NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg): POSIX's open()
descriptor_ = open(name.c_str(), kOpenFlags);
if (descriptor_ < 0) {
return false;
}
bool const opened{Configure(baud_rate)};
if (opened) {
// What lay in the buffers from before goes, if it can; left there, it
// starts the first line read, which the link passes on as a line of its
// own.
max_matrix::Discard(tcflush(descriptor_, TCIOFLUSH));
} else {
Close();
}
return opened;
}

// Takes the open port for itself and sets it up as Open() says. Returns false
// if it is taken or does not take the baud rate. FN-11: not const, as it
// changes the port this object stands for, through its descriptor.
// NOLINTNEXTLINE(readability-make-member-function-const)
bool ControlSerialPort::Configure(uint32_t baud_rate) {
/* the modem lines ignored, and receiving on */
constexpr tcflag_t kLocalReceive{CLOCAL | CREAD};
/* two stop bits and the hardware handshake, both off for SerialControl */
constexpr tcflag_t kTwoStopsHandshake{CSTOPB | CRTSCTS};
termios settings{};

// NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg): POSIX's ioctl()
bool opened{(ioctl(descriptor_, TIOCEXCL) == 0) &&
(tcgetattr(descriptor_, &settings) == 0)};
bool const taken{(ioctl(descriptor_, TIOCEXCL) == 0) &&
(tcgetattr(descriptor_, &settings) == 0)};
cfmakeraw(&settings);
max_matrix::Bit<tcflag_t>::SetBits(settings.c_cflag, kLocalReceive);
max_matrix::Bit<tcflag_t>::ClearBits(settings.c_cflag, kTwoStopsHandshake);
settings.c_cc[VMIN] = 1;
settings.c_cc[VTIME] = 0;
// glibc's cfsetspeed() takes a rate as its number as well as its B constant,
// so no table maps one to the other.
opened = opened && (cfsetspeed(&settings, baud_rate) == 0) &&
(tcsetattr(descriptor_, TCSANOW, &settings) == 0);
if (opened) {
tcflush(descriptor_, TCIOFLUSH);
} else {
Close();
}
return opened;
return taken && (cfsetspeed(&settings, baud_rate) == 0) &&
(tcsetattr(descriptor_, TCSANOW, &settings) == 0);
}

std::vector<std::string> ControlSerialPort::List() {
Expand Down Expand Up @@ -280,7 +295,9 @@ bool ControlSerialPort::Read(std::string& data) {

void ControlSerialPort::Close() {
if (descriptor_ >= 0) {
close(descriptor_);
// close() frees the descriptor even when it reports an error, and there is
// nothing to try again.
max_matrix::Discard(close(descriptor_));
}
descriptor_ = -1;
}
Expand Down
4 changes: 3 additions & 1 deletion control/ControlSerialPort.h
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@ class ControlSerialPort final : public ControlPort {
void* handle_;
#else
int descriptor_{-1};

MAXMATRIX_NODISCARD bool Configure(uint32_t baud_rate);
#endif

public:
Expand Down Expand Up @@ -70,7 +72,7 @@ class ControlSerialPort final : public ControlPort {
*
* \return The names, sorted.
*/
static std::vector<std::string> List();
MAXMATRIX_NODISCARD static std::vector<std::string> List();

MAXMATRIX_NODISCARD bool IsOpen() const override;
bool Write(std::string const& data) override;
Expand Down
14 changes: 10 additions & 4 deletions control/ControlTcpPort.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@

#include "ControlStream.h"
#include "ControlTcpPort.h"
#include "MaxMatrixAttributes.h"
#include "Utility/Bit.h"

namespace {
Expand All @@ -42,7 +43,9 @@ using Length = int;
constexpr int kSendFlags{0};

bool WouldBlock() { return WSAGetLastError() == WSAEWOULDBLOCK; }
void CloseSocket(Socket socket) { closesocket(socket); }
// The socket is gone even when closing reports an error, and there is nothing
// to try again.
void CloseSocket(Socket socket) { max_matrix::Discard(closesocket(socket)); }
int Poll(pollfd* descriptor, int timeout) {
return WSAPoll(descriptor, 1, timeout);
}
Expand All @@ -58,7 +61,8 @@ using Length = size_t;
constexpr int kSendFlags{MSG_NOSIGNAL};

bool WouldBlock() { return (errno == EAGAIN) || (errno == EWOULDBLOCK); }
void CloseSocket(Socket socket) { close(socket); }
// As on Windows.
void CloseSocket(Socket socket) { max_matrix::Discard(close(socket)); }
int Poll(pollfd* descriptor, int timeout) {
return poll(descriptor, 1, timeout);
}
Expand Down Expand Up @@ -99,7 +103,8 @@ bool ControlTcpPort::Open(uint16_t port) {
socket_ = static_cast<intptr_t>(socket(AF_INET, SOCK_STREAM, 0));
if (socket_ == kNone) {
#ifdef _WIN32
WSACleanup();
// It fails only without the WSAStartup() above.
max_matrix::Discard(WSACleanup());
#endif
return false;
}
Expand Down Expand Up @@ -165,6 +170,7 @@ void ControlTcpPort::Close() {
CloseSocket(ToSocket(socket_));
socket_ = kNone;
#ifdef _WIN32
WSACleanup();
// It fails only without the WSAStartup() of Open().
max_matrix::Discard(WSACleanup());
#endif
}
Loading