Markdown quietly won.

It started as a way for programmers to write README files. Today it’s the language of notes apps, blogs, documentation sites, help centers and team wikis. And over the past year it became something else: the language AI speaks. Ask ChatGPT, Claude or Gemini a question and the answer comes back in Markdown. Coding agents write their plans, specs and reports in Markdown. Even the instructions we give them live in Markdown files.

Yet reading and writing Markdown still feels like reading the back of a sweater. Pound signs, asterisks, brackets, pipes. Most apps give you two options: stare at the symbols, or split your screen in half and watch a preview update next to the text you’re actually typing.

I wanted neither. So I built Markify.

A page, not a code file

Open a Markdown file in Markify and it looks like a finished document. Headings are headings. Checklists have real checkboxes. Tables are tables. Code is colored, math is typeset, diagrams are drawn. You write directly on that page, the way you would in Pages or Word.

Caption: A Markdown file in Markify: tags, a note, a checklist and a table, ready to edit.

The difference is what happens when you save. Markify doesn’t turn your work into a proprietary format or lock it inside a database. Your file stays a plain Markdown file, the same one your blog, your team, your Git repository or your AI tools already understand. If you ever want to see the raw text, it’s one click away. You just don’t have to.

Markdown from anywhere

Not every Markdown file lives on your Mac. Documentation sits on GitHub. Someone sends you a link. A project you’re curious about has twenty pages of docs in a repository you’ll never clone.

Markify opens them all. Paste a link to any Markdown file on the web and it opens as a clean page. Paste the address of a GitHub or GitLab repository and you can browse its documentation like a little library. Private repositories work too. Whatever you open is your own copy: your edits never leave your Mac.

And for the files already on your Mac, you don’t even need to open the app. Select one in Finder, press Space, and Quick Look shows it properly formatted, images, math and diagrams included.

A home for what your AI writes

This is the part that surprised me most while building Markify.

If you work with AI coding tools like Claude Code, Codex or OpenCode, you know the feeling. The agent finishes a task and leaves you a long report in the terminal: what it changed, what it tested, what it’s unsure about. Or it writes a plan you’re supposed to review before it starts. That’s real reading, and a terminal is a terrible place to do it.

With Markify, your agent can send its report straight to the app, where it opens as a proper document you can read, edit and keep. The same goes for the files that steer these tools, the AGENTS.md and CLAUDE.md files that teams now maintain as carefully as their code.

Markify also speaks Google’s Open Knowledge Format, a way of packaging knowledge as a folder of Markdown files so AI agents can use it. Open one and Markify understands how the pieces connect and points out anything that’s broken.

In the next update, Markify will also notice when another app changes a file you have open, whether that’s an agent, a sync service or a teammate’s commit. You choose to keep your version, reload theirs, or merge the two.

Everything a document needs

Tables, checklists, footnotes, highlighted notes and warnings, code with syntax colors, math, and diagrams that draw themselves from a few lines of text. Keep your notes together in a library that shows every Markdown file in a folder, one click away.

When it’s time to share with someone who doesn’t use Markdown, export to a web page or a PDF in a couple of clicks.

Apple Intelligence, on your Mac

Markify uses Apple Intelligence to proofread, rewrite, change the tone of a paragraph, summarize a long document, or suggest a title and tags. Every suggestion can be compared with your original, accepted or reverted. It all runs on your Mac.

Made for the Mac, and only the Mac

Markify isn’t a website wrapped in an app. It’s built with Apple’s own tools, so it feels at home next to Notes and Pages, and follows the Mac conventions you already know.

It’s also private by design. No account to create. No ads. No tracking of what you write. Your files stay wherever you save them.

Try it

Markify is free and runs on Apple silicon and Intel Macs with macOS 26 or later.

Download Markify: https://github.com/spaquet/markify/releases/latest
Learn more: https://spaquet.github.io/markify/

The install guide walks you through it in a minute in case you encounter some MacOS Safe Guard issues: https://spaquet.github.io/markify/help/updates.html

I Built a Mac App That Makes Markdown Look Effortless was originally published in Towards Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

In the previous articles of this Load Balancer series, we built our own Load Balancer using Java and Spring Boot and gradually added features such as health checks, retry and fallback, circuit breakers, and connection/read timeouts.

So far, our Load Balancer has been using the Round Robin algorithm to select backend servers.

Round Robin is simple and works well when all backend servers have similar capabilities.

But what happens when our backend servers are not equally powerful?

For example:

Server 1 → 8 CPU cores, 16 GB RAM
Server 2 → 2 CPU cores, 4 GB RAM

Should both servers receive exactly the same amount of traffic?

Not necessarily.

This is where Weighted Round Robin can help.

In this article, we will understand how Weighted Round Robin works and how we can design our Load Balancer so that the routing algorithm itself becomes configurable.

Buy Me a Coffee

1. What is Round Robin?

Before understanding Weighted Round Robin, let’s quickly look at the algorithm we already implemented.

Suppose we have two backend servers:

Server 1 → localhost:8080
Server 2 → localhost:8081

With Round Robin, requests are distributed sequentially:

Request 1 → 8080
Request 2 → 8081
Request 3 → 8080
Request 4 → 8081
Request 5 → 8080

So the pattern is:

8080 → 8081 → 8080 → 8081 → ...

The main characteristic of Round Robin is that every server gets approximately the same number of requests.

This is simple and works very well when the backend servers have similar capabilities.

But that assumption isn’t always true.

2. The Problem with Normal Round Robin

Imagine that we have the following two servers:

Server 1
8 CPU cores
16 GB RAM

Server 2
2 CPU cores
4 GB RAM

Server 1 is clearly more powerful.

However, with normal Round Robin, we still distribute traffic like this:

8080
8081
8080
8081
8080
8081

Both servers receive approximately 50% of the traffic.

This may not be the most efficient distribution.

If Server 1 can comfortably handle more traffic, we would ideally like to send more requests to it.

Instead of treating all servers equally, we can assign a weight to each server.

This leads us to Weighted Round Robin.

3. What is Weighted Round Robin?

Weighted Round Robin is an extension of the traditional Round Robin algorithm.

The key difference is:

Round Robin treats servers equally, while Weighted Round Robin distributes traffic according to the configured weight of each server.

For example:

Server 8080 → Weight 3
Server 8081 → Weight 1

The higher the weight, the more traffic that server should receive.

A simple request sequence could therefore be:

8080
8080
8080
8081

So the distribution ratio becomes:

8080 : 8081 = 3 : 1

Over a large number of requests, Server 8080 should receive approximately three times as much traffic as Server 8081.

4. Understanding the Weight

It’s important to understand that a weight does not mean the server can process exactly that number of requests.

For example:

8080 → Weight 3
8081 → Weight 1

doesn’t mean “Send exactly 3 requests to 8080 and 1 request to 8081”.

Instead, it represents a relative traffic ratio.

For example, over 100 requests, we would approximately expect:

8080 → 75 requests
8081 → 25 requests

because the total weight is:

3 + 1 = 4

Therefore:

8080 → 3/4 = 75%

8081 → 1/4 = 25%

The exact sequence may vary depending on the implementation, but the goal is to maintain the configured ratio over time.

5. Example with Three Servers

Let’s make the example slightly more interesting.

Suppose we have:

Server A → Weight 5
Server B → Weight 3
Server C → Weight 2

The total weight is:

5 + 3 + 2 = 10

So approximately:

Server A → 50%
Server B → 30%
Server C → 20%

This gives us much more control over how traffic is distributed.

For example, if Server A is significantly more powerful than Server C, we can give it a higher weight.

6. Where Can Weighted Round Robin Be Useful?

Weighted Round Robin can be useful in several situations.

Different server capacities

Suppose we have:

Server A → 8 CPU cores
Server B → 4 CPU cores
Server C → 2 CPU cores

We could configure:

Server A → Weight 4
Server B → Weight 2
Server C → Weight 1

This allows the more powerful servers to receive more traffic.

Different instance sizes

In cloud environments, we may have backend instances with different resource configurations.

A larger instance can be assigned a higher weight.

Gradually introducing a new server

Suppose our existing production server has:

Server A → Weight 9

and we introduce:

Server B → Weight 1

Server B will initially receive a much smaller percentage of traffic.

This can be useful when gradually introducing additional capacity.

7. How Can We Implement Weighted Round Robin?

For our custom Load Balancer, we are going to keep the implementation simple.

Suppose we have:

8080 → Weight 3
8081 → Weight 1

We can conceptually create a weighted sequence:

8080
8080
8080
8081

Then we can use a counter to continuously move through this sequence.

For example:

int index = Math.floorMod(
        counter.getAndIncrement(),
        weightedServers.size()
);

This gives us a simple repeating weighted pattern.

So instead of:

8080 → 8081 → 8080 → 8081

we can get:

8080 → 8080 → 8080 → 8081

This is a straightforward way to demonstrate the concept in our custom Load Balancer.

Note: This is a simplified implementation for learning purposes. Production load balancers can use more sophisticated approaches such as Smooth Weighted Round Robin.

8. But There Is Another Problem

Now that we have two algorithms:

Round Robin
Weighted Round Robin

we need to think about our application design.

Where should the routing algorithm live?

If we put both algorithms directly inside our LoadBalancerService, we could end up with something like:

if (algorithm.equals("ROUND_ROBIN")) {
    // Round Robin logic
} else if (algorithm.equals("WEIGHTED_ROUND_ROBIN")) {
    // Weighted Round Robin logic
}

This may work initially.

But what happens when we introduce:

Least Connections
IP Hash
Random

Our service will keep growing.

Every new algorithm will require changes to the existing service.

This is not the design we want.

9. Separating Server Selection from Request Processing

Our Load Balancer actually has multiple responsibilities.

For example:

Health Check
Circuit Breaker
Retry
Timeout
Request Forwarding
Server Selection

We can separate the server selection responsibility from the rest of the request-processing logic.

The Load Balancer should be responsible for things such as:

Should I send this request?
Is the server healthy?
Should I retry?
Has the circuit opened?
Did the request timeout?

But it doesn’t necessarily need to know “How exactly should I select the next server?”

That can be delegated to a separate strategy.

10. Using the Strategy Pattern

For this, we can use the Strategy Pattern.

We create a common interface:

public interface LoadBalancingStrategy {
  Server selectServer(
    List<Server> servers,
    Set<String> excludedServers
  );
}

Now each algorithm implements this interface.

Our design becomes:

LoadBalancingStrategy
        |
        +---- RoundRobinStrategy
        |
        +---- WeightedRoundRobinStrategy

The main LoadBalancerService doesn't need to know the internal implementation of either algorithm.

It simply asks the strategy:

"Give me the next server."

11. RoundRobinStrategy

Our existing Round Robin logic can now move into:

RoundRobinStrategy

This class is responsible only for Round Robin server selection.

For example:

int index = Math.floorMod(
        counter.getAndIncrement(),
        servers.size()
);

return servers.get(index);

The important thing is that this logic no longer needs to live inside the main Load Balancer service.

12. WeightedRoundRobinStrategy

Similarly, we create:

WeightedRoundRobinStrategy

This class implements the same interface:

LoadBalancingStrategy

but contains the Weighted Round Robin logic.

For example:

8080 → Weight 3
8081 → Weight 1

can produce:

8080
8080
8080
8081

The strategy then selects servers from this weighted sequence.

This gives us a clean separation between the two algorithms.

13. Adding Weight to Our Server

Our existing Server object needs to store the weight.

Conceptually, we add:

private int weight;

Now a server can be represented as:

Server 8080 → weight = 3
Server 8081 → weight = 1

The WeightedRoundRobinStrategy can use this value while selecting the next server.

14. Making the Algorithm Configurable

Now comes one of the most important improvements.

I don’t want to modify Java code whenever I want to change the routing algorithm.

Instead, we can configure it using application.properties.

For example:

load-balancer.algorithm=ROUND_ROBIN

If we want Weighted Round Robin:

load-balancer.algorithm=WEIGHTED_ROUND_ROBIN

Now the routing algorithm becomes a configuration decision.

We don’t need to rewrite our LoadBalancerService.

15. Algorithm Enum

We can represent the supported algorithms using an enum:

public enum LoadBalancingAlgorithm {
    ROUND_ROBIN,
    WEIGHTED_ROUND_ROBIN
}

This gives us a clean and strongly typed representation of the available algorithms.

If we introduce another algorithm in the future, we can add another value.

16. Strategy Factory

Now we need something that can select the correct strategy based on the configuration.

For this, we can introduce:

LoadBalancingStrategyFactory

The factory reads the configured algorithm and returns the appropriate strategy.

For example:

application.properties
        |
        ↓
ROUND_ROBIN
        |
        ↓
Strategy Factory
        |
        ↓
RoundRobinStrategy

Or:

application.properties
        |
        ↓
WEIGHTED_ROUND_ROBIN
        |
        ↓
Strategy Factory
        |
        ↓
WeightedRoundRobinStrategy

Our LoadBalancerService only needs to work with:

LoadBalancingStrategy

It doesn’t need to know which implementation was selected.

17. What About Retry and Circuit Breaker?

This is particularly important because our Load Balancer already contains Retry and Circuit Breaker functionality.

Introducing multiple routing strategies should not break those features.

Suppose our first request is sent to:

8080

and the request fails.

Our retry mechanism should select another eligible server.

But the retry mechanism doesn’t need to know whether the Load Balancer is using:

Round Robin

or:

Weighted Round Robin

Instead, it asks the currently selected strategy for the next server.

The flow becomes:

Request
   ↓
Load Balancer
   ↓
Select server using strategy
   ↓
Forward request
   ↓
Failure
   ↓
Retry
   ↓
Ask same strategy for another server
   ↓
Forward request

This is an important architectural improvement.

The retry mechanism controls whether another attempt should happen, while the load-balancing strategy controls which server should be selected.

18. Avoiding the Same Server During Retry

Suppose we have:

8080
8081

The first attempt selects:

8080

but it fails.

We don’t want our retry to immediately select 8080 again.

Therefore, we maintain a set of attempted servers.

For example:

Set<String> attemptedServers = new HashSet<>();

After selecting 8080:

attemptedServers.add(server.getUrl());

The next strategy call can then exclude already attempted servers.

This allows both Round Robin and Weighted Round Robin to work with our existing Retry and Fallback functionality.

19. Maximum Retry Attempts

We also need to consider how many times we should retry.

For example:

load-balancer.max-attempts=2

What if only one server is available?

We shouldn’t call the same server twice just because the maximum attempts is two.

So we can calculate:

int attempts = Math.min(
        maxAttempts,
        availableServers.size()
);

If:

maxAttempts = 2
availableServers = 1

then:

attempts = 1

If:

maxAttempts = 2
availableServers = 2

then:

attempts = 2

This keeps our retry behavior simple and avoids unnecessary repeated requests to the same backend.

20. Final Architecture

After this improvement, our architecture looks like:

                        Client
                          |
                          ↓
                LoadBalancerService
                          |
        +-----------------+----------------+
        |                 |                |
        ↓                 ↓                ↓
   Health Check      Circuit Breaker      Retry
                                             |
                                             ↓
                                  LoadBalancingStrategy
                                             |
                            +----------------+----------------+
                            |                                 |
                            ↓                                 ↓
                   RoundRobinStrategy             WeightedRoundRobinStrategy

The algorithm is selected through:

load-balancer.algorithm

This means our core service no longer needs to contain algorithm-specific server-selection code.

21. Why Is This Design Better?

There are several benefits to this approach.

1. Easy to switch algorithms

We can change:

load-balancer.algorithm=ROUND_ROBIN

to:

load-balancer.algorithm=WEIGHTED_ROUND_ROBIN

without changing the core request-forwarding code.

2. Separation of responsibilities

The Load Balancer handles:

• Health checks
• Circuit Breaker
• Retry
• Timeouts
• Request forwarding

The strategy handles:

• Server selection

3. Easier to extend

If we want to introduce:

Least Connections
IP Hash
Random

we can implement another strategy rather than modifying the entire service.

4. Existing features remain reusable

Our Retry, Circuit Breaker, Health Check, and Timeout mechanisms don’t need to understand the internal details of the routing algorithm.

22. A Note About Production Implementations

Our goal in this series is to build a Load Balancer from scratch so that we can understand the underlying concepts.

Therefore, our Weighted Round Robin implementation is intentionally simple.

Real-world load balancers may use more sophisticated algorithms such as:

• Smooth Weighted Round Robin
• Dynamic load-based routing
• Least Connections
• Latency-aware routing
• Resource-aware routing

A production implementation may also dynamically adjust weights based on real-time server metrics.

For example:

CPU usage
Memory usage
Active connections
Response time

These metrics can be used to make routing decisions more dynamic.

23. Future Possibilities

The Strategy Pattern gives us a foundation for adding more algorithms in future tutorials.

Our architecture can eventually become:

LoadBalancingStrategy
        |
        +---- Round Robin
        |
        +---- Weighted Round Robin
        |
        +---- Least Connections
        |
        +---- IP Hash
        |
        +---- Random

And the selection can continue to be controlled through configuration.

This makes our custom Load Balancer easier to evolve as we introduce more advanced concepts.

Conclusion

In this tutorial, we took our existing Round Robin Load Balancer and introduced Weighted Round Robin.

The main difference is simple:

Round Robin:

Every server gets approximately equal traffic.

Weighted Round Robin:

Servers receive traffic according to their configured weights.

For example:

Server A → Weight 3
Server B → Weight 1

means that Server A should receive approximately three times the traffic of Server B over time.

But the bigger improvement was not just the new algorithm.

We also changed the architecture of our Load Balancer.

Instead of tightly coupling server selection with LoadBalancerService, we introduced a common LoadBalancingStrategy interface.

LoadBalancingStrategy
        |
        +---- RoundRobinStrategy
        |
        +---- WeightedRoundRobinStrategy

The routing algorithm can now be selected through configuration:

load-balancer.algorithm=ROUND_ROBIN

or:

load-balancer.algorithm=WEIGHTED_ROUND_ROBIN

This allows us to switch algorithms without rewriting the core request-forwarding logic.

More importantly, our Retry and Circuit Breaker implementations remain independent of the routing algorithm.

The responsibilities are now clearly separated:

Retry decides whether we should try again.

The Load Balancing Strategy decides which server should receive the attempt.

This gives us a much better foundation for adding more advanced load-balancing algorithms in the future.

Building a Configurable Load Balancer in Java & Spring Boot — Weighted Round Robin was originally published in Towards Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

In this post, a toggle-flick tool is demonstrated. Click-drag the ball to the blue center while trying to counteract the random pattern.

Non-compensatory

The pointerdown and pointerup user control movements are independent of the randomly applied 3d ball movements.

<!DOCTYPE>
<html>
<head></head>
<body>
<div class="javascript_css"></div>
<script>
function toggle0(documentElement) {
  
  if (document.getElementById("label0") == null) {
  
    var labelElement = document.createElement("label");
    labelElement.setAttribute("id", "label0");
    labelElement.setAttribute("class", "label_simple");
    labelElement.setAttribute("onpointerdown", "processEvent_pointerdown(event)");
    labelElement.setAttribute("onpointerup", "processEvent_pointerup(event)");
    labelElement.style.position = "absolute";
    labelElement.style.top = "60px";
    labelElement.style.left = "0px";
    labelElement.style.display = "inline-block";
    labelElement.style.width = "300px";
    labelElement.style.height = "20px";
    labelElement.style.border = "1px solid gray";
    labelElement.style.borderRadius = "10px";
    labelElement.style.backgroundColor = "hsl(0 100% 100%)";
    labelElement.style.background = "linear-gradient(to left, #eeeeee, #eeeeee 25%, #9198e5 50%, #eeeeee 75%, #eeeeee 100%)";
    labelElement.style.zIndex = "5";
    documentElement.appendChild(labelElement);
    
    var spanElement = document.createElement("span");
    spanElement.setAttribute("id", "span0");
    spanElement.setAttribute("class", "span_simple");
    spanElement.style.cursor = "pointer";
    spanElement.style.position = "absolute";
    spanElement.style.top = "0px";
    spanElement.style.left = `${parseInt(document.getElementById("label0").style.width.split("px")[0])/2}px`;
    spanElement.style.width = document.getElementById("label0").style.height;
    spanElement.style.height = document.getElementById("label0").style.height;
    spanElement.style.backgroundColor = "hsl(30 100% 90%)";
    spanElement.style.background ="radial-gradient(ellipse 50% 50% at 30% 25%, hsl(30 100% 100%), hsl(30 100% 40%) 100%)";
    spanElement.style.boxShadow = "inset 0px 0px 0px rgba(255,255,255,0.6), inset 0px 0px 0px rgba(0,0,0,0.6)";
    spanElement.style.transition = "0.5s";
    spanElement.style.border = `2px solid ${spanElement.style.backgroundColor}`;
    spanElement.style.borderRadius = parseInt(document.getElementById("label0").style.height.split("px")[0]/2)+"px";
    spanElement.style.fontSize = "12px";
    spanElement.style.touchAction =  "none";
    spanElement.innerText = "";
    document.getElementById("label0").appendChild(spanElement);
    document.getElementById("span0").x0 = 0;
    document.getElementById("span0").x1 = 0;
    
    var pElement = document.createElement("p");
    pElement.setAttribute("id", "p0");
    pElement.setAttribute("class", "p_simple");
    pElement.setAttribute("onclick", "processEvent_click()");
    pElement.style.position = "absolute";
    pElement.style.top = "170px";
    pElement.style.left = "0px";
    pElement.style.width = "300px";
    pElement.style.height = "100px";
    pElement.style.backgroundColor = "hsl(60 100% 90%)";
    pElement.style.overflow = "scroll";
    documentElement.appendChild(pElement);
    document.getElementById("p0").clicked = false;
    document.getElementById("p0").count = 0;
    document.getElementById("p0").innerHTML += "clicked: "+document.getElementById("p0").clicked+"<br>";
    
  }
  
}

function processEvent_pointerdown(event) {
  
  document.getElementById("span0").style.border = "4px solid indianred";
  
  event.target.x0 = event.offsetX;
  document.getElementById("p0").innerHTML += "event.target.x0: "+event.target.x0+"<br>";
    
}

function processEvent_pointerup(event) {

  document.getElementById("span0").style.border = "2px solid hsl(30 100% 90%)";
  
  event.target.x1 = event.offsetX;
  document.getElementById("p0").innerHTML += "event.target.x1: "+event.target.x1+"<br>";
  
  var dx = event.target.x1 - event.target.x0;
  document.getElementById("p0").innerHTML += "dx: "+dx+"<br>";
  
  var spanLeft = parseInt(document.getElementById("span0").style.left.split("px")[0]);
  var labelWidth = parseInt(document.getElementById("label0").style.width.split("px")[0]);
  var spanWidth = parseInt(document.getElementById("span0").style.width.split("px")[0]);
  
  if (spanLeft+dx < labelWidth+spanWidth) { document.getElementById("span0").style.left = `${spanLeft+dx}px`; } else { document.getElementById("span0").style.left = `${labelWidth-spanWidth}px`; }
  if (spanLeft+dx > 0) { document.getElementById("span0").style.left = `${spanLeft+dx}px`; } else { document.getElementById("span0").style.left = "0px"; }

}
</script>
<script>
async function mainloop() {
  document.getElementById("p0").innerHTML += "clicked: "+document.getElementById("p0").clicked+"<br>";
  
  await functionName1();  	
  if (document.getElementById("p0").clicked == true) {
    // keep running for 30 mins:  (30 mins) * (60 secs / 1 min) * (1 count / 2.5 secs) = 720 counts
    if (Number(document.getElementById("p0").count) < 300) {
      await mainloop();
    }
  } else {
    // stop count.
    document.getElementById("p0").clicked = false; // reset to original state.
    document.getElementById("p0").count = 0;
  } 
	
}


async function functionName1() {
  
  // task: move 3d ball left and right.
  // document.getElementById("p0").innerHTML += "task1<br>"; 
  var len = parseInt(document.getElementById("label0").style.width.split("px")[0]) - parseInt(document.getElementById("span0").style.width.split("px")[0]);
  var value = [len/4, len/2, (len/4)+(len/2), len];
  var maximum = value.length;
  var minimum = 0;
  var index = Math.floor(Math.random()*(maximum-minimum)+minimum);
  document.getElementById("p0").innerHTML += "index: "+index+"<br>";
  document.getElementById("span0").style.left = value.at(index)+"px";
  
  
  document.getElementById("p0").count = Number(document.getElementById("p0").count) + 1;	
  

  document.getElementById("p0").innerHTML += "count: "+document.getElementById("p0").count+"<br>";
  await new Promise(r => setTimeout(r, 500));
  
}


async function processEvent_click() {
document.getElementById("p0").innerHTML += "clicked: "+document.getElementById("p0").clicked+"<br>";

  document.getElementById("p0").innerHTML += "count: "+document.getElementById("p0").count+"<br>";
  
  if (document.getElementById("p0").count == 0) {
    // start count.
    document.getElementById("p0").clicked = true;
    await mainloop();
  } else {
    // stop count.
    document.getElementById("p0").clicked = false; // reset to original state.
    document.getElementById("p0").count = 0;
  }
    
  document.getElementById("p0").innerHTML += "clicked: "+document.getElementById("p0").clicked+"<br>";
  
}
</script>
<script>
border();

function border() {
  
  document.getElementsByClassName("javascript_css")[0].style.position = "absolute";
  document.getElementsByClassName("javascript_css")[0].style.width = "300px";
  document.getElementsByClassName("javascript_css")[0].style.height = "50px"; 
  document.getElementsByClassName("javascript_css")[0].style.border = "1px solid gray";
  document.getElementsByClassName("javascript_css")[0].style.borderRadius = "2px";
  document.getElementsByClassName("javascript_css")[0].style.fontSize = "12px";
  document.getElementsByClassName("javascript_css")[0].innerHTML = "Click-on the yellow box to start or stop the 3d ball moving left or right. Click-drag the 3d ball to the blue center area.";

  toggle0(document.getElementsByClassName("javascript_css")[0]);

}
</script>
</body>
</html>

Compensatory version

The pointerdown and pointerup user control movements are subtracted from the randomly applied 3d ball movements.

A compensatory task is useful to measure learning of the pattern that the user needs to counteract.

<!DOCTYPE>
<html>
<head></head>
<body>
<div class="javascript_css"></div>
<script>
function toggle0(documentElement) {
  
  if (document.getElementById("label0") == null) {
  
    var labelElement = document.createElement("label");
    labelElement.setAttribute("id", "label0");
    labelElement.setAttribute("class", "label_simple");
    labelElement.setAttribute("onpointerdown", "processEvent_pointerdown(event)");
    labelElement.setAttribute("onpointerup", "processEvent_pointerup(event)");
    labelElement.style.position = "absolute";
    labelElement.style.top = "60px";
    labelElement.style.left = "0px";
    labelElement.style.display = "inline-block";
    labelElement.style.width = "300px";
    labelElement.style.height = "20px";
    labelElement.style.border = "1px solid gray";
    labelElement.style.borderRadius = "10px";
    labelElement.style.backgroundColor = "hsl(0 100% 100%)";
    labelElement.style.background = "linear-gradient(to left, #eeeeee, #eeeeee 25%, #9198e5 50%, #eeeeee 75%, #eeeeee 100%)";
    labelElement.style.zIndex = "5";
    documentElement.appendChild(labelElement);
    
    var spanElement = document.createElement("span");
    spanElement.setAttribute("id", "span0");
    spanElement.setAttribute("class", "span_simple");
    spanElement.style.cursor = "pointer";
    spanElement.style.position = "absolute";
    spanElement.style.top = "0px";
    spanElement.style.left = `${parseInt(document.getElementById("label0").style.width.split("px")[0])/2}px`;
    spanElement.style.width = document.getElementById("label0").style.height;
    spanElement.style.height = document.getElementById("label0").style.height;
    spanElement.style.backgroundColor = "hsl(30 100% 90%)";
    spanElement.style.background ="radial-gradient(ellipse 50% 50% at 30% 25%, hsl(30 100% 100%), hsl(30 100% 40%) 100%)";
    spanElement.style.boxShadow = "inset 0px 0px 0px rgba(255,255,255,0.6), inset 0px 0px 0px rgba(0,0,0,0.6)";
    spanElement.style.transition = "0.5s";
    spanElement.style.border = `2px solid ${spanElement.style.backgroundColor}`;
    spanElement.style.borderRadius = parseInt(document.getElementById("label0").style.height.split("px")[0]/2)+"px";
    spanElement.style.fontSize = "12px";
    spanElement.style.touchAction =  "none";
    spanElement.innerText = "";
    document.getElementById("label0").appendChild(spanElement);
    document.getElementById("span0").x0 = 0;
    document.getElementById("span0").x1 = 0;
    document.getElementById("span0").user = 0;
    
    var pElement = document.createElement("p");
    pElement.setAttribute("id", "p0");
    pElement.setAttribute("class", "p_simple");
    pElement.setAttribute("onclick", "processEvent_click()");
    pElement.style.position = "absolute";
    pElement.style.top = "170px";
    pElement.style.left = "0px";
    pElement.style.width = "300px";
    pElement.style.height = "100px";
    pElement.style.backgroundColor = "hsl(60 100% 90%)";
    pElement.style.overflow = "scroll";
    documentElement.appendChild(pElement);
    document.getElementById("p0").clicked = false;
    document.getElementById("p0").count = 0;
    document.getElementById("p0").innerHTML += "clicked: "+document.getElementById("p0").clicked+"<br>";
    
  }
  
}

function processEvent_pointerdown(event) {
  
  document.getElementById("span0").style.border = "4px solid indianred";
  
  event.target.x0 = event.offsetX;
  document.getElementById("p0").innerHTML += "event.target.x0: "+event.target.x0+"<br>";
    
}

function processEvent_pointerup(event) {

  document.getElementById("span0").style.border = "2px solid hsl(30 100% 90%)";
  
  event.target.x1 = event.offsetX;
  document.getElementById("p0").innerHTML += "event.target.x1: "+event.target.x1+"<br>";
  
  var dx = event.target.x1 - event.target.x0;
  document.getElementById("p0").innerHTML += "dx: "+dx+"<br>";
  
  var spanLeft = parseInt(document.getElementById("span0").style.left.split("px")[0]);
  var labelWidth = parseInt(document.getElementById("label0").style.width.split("px")[0]);
  var spanWidth = parseInt(document.getElementById("span0").style.width.split("px")[0]);
  
  if (spanLeft+dx < labelWidth+spanWidth) { 
    // document.getElementById("span0").style.left = `${spanLeft+dx}px`;
    document.getElementById("span0").user = dx;
  } else {
    document.getElementById("span0").style.left = `${labelWidth-spanWidth}px`;
  }
  if (spanLeft+dx > 0) {
    // document.getElementById("span0").style.left = `${spanLeft+dx}px`;
    document.getElementById("span0").user = dx;
  } else {
    document.getElementById("span0").style.left = "0px";
  }

}
</script>
<script>
async function mainloop() {
  document.getElementById("p0").innerHTML += "clicked: "+document.getElementById("p0").clicked+"<br>";
  
  await functionName1();  	
  if (document.getElementById("p0").clicked == true) {
    // keep running for 30 mins:  (30 mins) * (60 secs / 1 min) * (1 count / 2.5 secs) = 720 counts
    if (Number(document.getElementById("p0").count) < 300) {
      await mainloop();
    }
  } else {
    // stop count.
    document.getElementById("p0").clicked = false; // reset to original state.
    document.getElementById("p0").count = 0;
  } 
	
}


async function functionName1() {
  
  // task: move 3d ball left and right.
  // document.getElementById("p0").innerHTML += "task1<br>"; 
  var len = parseInt(document.getElementById("label0").style.width.split("px")[0]) - parseInt(document.getElementById("span0").style.width.split("px")[0]);
  var value = [len/4, len/2, (len/4)+(len/2), len].map((v,i) => { return v/2; });
  var maximum = value.length;
  var minimum = 0;
  var index = Math.floor(Math.random()*(maximum-minimum)+minimum);
  document.getElementById("p0").innerHTML += "index: "+index+"<br>"; ;
  
  // Non-compensatory.
  // document.getElementById("span0").style.left = value.at(index)+"px";
  // OR
  // Compensatory.
  var left0 = value.at(index) + parseInt(document.getElementById("span0").user);
  document.getElementById("span0").style.left = left0+"px";
  
  document.getElementById("p0").count = Number(document.getElementById("p0").count) + 1;	
  

  document.getElementById("p0").innerHTML += "count: "+document.getElementById("p0").count+"<br>";
  await new Promise(r => setTimeout(r, 500));
  
}


async function processEvent_click() {
document.getElementById("p0").innerHTML += "clicked: "+document.getElementById("p0").clicked+"<br>";

  document.getElementById("p0").innerHTML += "count: "+document.getElementById("p0").count+"<br>";
  
  if (document.getElementById("p0").count == 0) {
    // start count.
    document.getElementById("p0").clicked = true;
    await mainloop();
  } else {
    // stop count.
    document.getElementById("p0").clicked = false; // reset to original state.
    document.getElementById("p0").count = 0;
  }
    
  document.getElementById("p0").innerHTML += "clicked: "+document.getElementById("p0").clicked+"<br>";
  
}
</script>
<script>
border();

function border() {
  
  document.getElementsByClassName("javascript_css")[0].style.position = "absolute";
  document.getElementsByClassName("javascript_css")[0].style.width = "300px";
  document.getElementsByClassName("javascript_css")[0].style.height = "50px"; 
  document.getElementsByClassName("javascript_css")[0].style.border = "1px solid gray";
  document.getElementsByClassName("javascript_css")[0].style.borderRadius = "2px";
  document.getElementsByClassName("javascript_css")[0].style.fontSize = "12px";
  document.getElementsByClassName("javascript_css")[0].innerHTML = "Click-on the yellow box to start or stop the 3d ball moving left or right. Click-drag the 3d ball to the blue center area.";

  toggle0(document.getElementsByClassName("javascript_css")[0]);

}
</script>
</body>
</html>

Good Luck with your workflows and Happy Practicing! 👋

🔔 Practicing Datscy @ Medium | 🌷 Practicing Datscy @ Dev.to

References

1. Linear-gradient MDN: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/gradient/linear-gradient

Self-Productivity Tool Series was originally published in Towards Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Integer overflow is easy to get wrong. Unsigned integers wrap around.
Signed integer overflow is undefined behavior.

If you want a calculation to stop at the minimum or maximum value instead, you need different arithmetic.

C++26 adds saturation arithmetic to <numeric>.

The feature is small, but there is some history behind it. The original proposal used names such as add_sat and sub_sat. Those names were changed before the feature was finalized.

This article covers what saturation arithmetic does, why the names changed, and how to use the new std::saturating_* functions.

First, the Problem: Wrapping and Undefined Behavior

In C and C++, unsigned integer arithmetic wraps around modulo 2^N.
For an N-bit unsigned integer, the range is: [0, 2^N - 1]
For example, an 8-bit unsigned integer can represent values from 0 to 255.

Add 10 to 255 and the result wraps around: 255 + 10 = 9

Signed integer overflow is different. Going beyond the range of the signed type results in undefined behavior.

Sometimes wrapping is exactly what you want. Sometimes it is not.
Consider an image with 8-bit pixel values. A white pixel has the value 255.
If you add 50 to it using normal unsigned arithmetic: 255 + 50 = 49
The value wraps around instead of staying at white.

Saturation arithmetic handles this differently. The result is kept inside the representable range. If the result is larger than the maximum, it becomes the maximum. If it is smaller than the minimum, it becomes the minimum.

For an 8-bit unsigned integer: 255 + 50 = 255

Instead of wrapping, the value stays at the upper limit.

Here is the difference:

Why This Matters for Systems Programming?

Saturation arithmetic is useful anywhere an integer has a fixed range.
Some examples:

• Audio processing: Keep sample values inside their valid range instead of letting them wrap.
• Image processing: Keep pixel values between their minimum and maximum values.
• Networking: Avoid unexpected wraparound when calculating lengths, offsets, and sizes.
• Embedded systems: Keep sensor and control values inside their defined limits.
• Game engines: Prevent fixed-range values from wrapping when they exceed their limits.

Before C++26, code that needed this behavior often used custom helper functions or compiler-specific builtins.

C++26 gives us standard library functions for it.

Why the Function Names Changed?

The original proposal for saturation arithmetic was P0543R3, written by Jens Maurer. It proposed functions with short names such as:

add_sat()
sub_sat()
mul_sat()
div_sat()

That naming did not make it into the final C++26 library.
Jan Schultke and Corentin Jabot later proposed P4052R0, which looked specifically at the naming. There were a few reasons for changing it.

1. The naming was inconsistent:
The proposal used: add_sat() but also saturate_cast() .
One used an abbreviation and the other did not.

2. saturating_add was already common:
The proposal compared existing code and other programming languages.
Names based on saturating_add were already common, including in Rust, Java, and C#.

3. The naming works better for future operations:
C++ may eventually add more forms of integer arithmetic.
Names such as:

saturating_add()
saturating_mul()
widening_mul()

follow a more consistent pattern where the operation describes what it does and the prefix describes the arithmetic variant. The committee adopted the saturating_ naming style.

So the final C++26 names are:

std::saturating_add
std::saturating_sub
std::saturating_mul
std::saturating_div
std::saturating_cast

The C++26 Saturation Toolkit

The functions are provided by: #include <numeric> .
They are constexpr and available in freestanding implementations.

The main operations are:

• std::saturating_add
• std::saturating_sub
• std::saturating_mul
• std::saturating_div
• std::saturating_cast

Let’s look at each one.

std::saturating_add

std::saturating_add performs addition without allowing the result to go outside the range of the type.

For example:

#include <numeric>
#include <iostream>
int main() {
    unsigned char pixel = 250;
    auto bright_pixel =
        std::saturating_add<unsigned char>(pixel, 10);
    std::cout << "Bright Pixel: "
              << static_cast<int>(bright_pixel)
              << '\n';
}

The mathematical result is 260. An unsigned char cannot represent 260, so the result is clamped to 255.

Bright Pixel: 255

One detail to remember:
These functions deliberately do not use the usual integral promotions.
The argument types need to match. This does not work:

unsigned char pixel = 250;
std::saturating_add(pixel, 10);

pixel is an unsigned char, while 10 is an int.

You can specify the type:

std::saturating_add<unsigned char>(pixel, 10);

or convert the second argument:

std::saturating_add(
    pixel,
    static_cast<unsigned char>(10)
);

std::saturating_sub

Subtraction is another common place where unsigned arithmetic can produce an unexpected result.

For example:

unsigned int health = 0;
unsigned int damage = 5;
unsigned int new_health =
    std::saturating_sub(health, damage);

Normal unsigned arithmetic would wrap around:

0 - 5 = 4,294,967,291

Saturating subtraction gives:

0 - 5 = 0

The same function also handles signed overflow.

#include <limits>
int max_int = std::numeric_limits<int>::max();
int result =
    std::saturating_sub(max_int, -10);

Mathematically, this is:

INT_MAX - (-10)

The result is larger than INT_MAX. Normal signed arithmetic would have undefined behavior. Saturating subtraction returns INT_MAX.

std::saturating_mul

Multiplication can exceed the range of an integer very quickly.
For example:

#include <numeric>
#include <iostream>
int main() {
    int a = 100000;
    int b = 100000;
    int product =
        std::saturating_mul(a, b);
    std::cout << product << '\n';
}

The mathematical result is:

100,000 × 100,000 = 10,000,000,000

That does not fit in a 32-bit signed int.
std::saturating_mul returns:

2,147,483,647

which is INT_MAX.

Negative results are handled in the same way:

int result =
    std::saturating_mul(100000, -100000);

The mathematical result is smaller than INT_MIN, so the result is clamped to:

-2,147,483,648

std::saturating_div

Division normally makes numbers smaller, so integer division overflowing looks strange at first.

There is one signed-integer case that matters:

INT_MIN / -1

For an 8-bit signed integer, the range is:

[-128, 127]

So:

-128 / -1 = 128

But 128 cannot be represented by int8_t. Normal signed integer arithmetic cannot represent that result.

With C++26:

#include <cstdint>
#include <numeric>
#include <iostream>
int main() {
    int8_t min_val = -128;
    int8_t divisor = -1;
    int8_t result =
        std::saturating_div(min_val, divisor);
    std::cout << static_cast<int>(result) << '\n';
}

The result is: 127
The value is clamped to the maximum representable value.
Division by zero is still invalid. Saturating arithmetic does not change that.

std::saturating_cast

Saturation is not limited to arithmetic operations. C++26 also provides std::saturating_cast for converting between integer types.

Suppose we have:

int32_t value = 5000;

and want an int8_t.

An int8_t can only represent: -128 ... 127
So 5000 does not fit.
With:

auto result =
    std::saturating_cast<int8_t>(value);

the result is: 127

The same idea works when converting negative values to unsigned types:

int32_t value = -50;
auto result =
    std::saturating_cast<uint32_t>(value);

Since an unsigned integer cannot represent a negative value, the result is clamped to: 0

This is useful when a conversion needs to preserve the destination type’s range instead of simply performing a normal integer conversion.

Closing Thoughts

C++26 adds standard library support for saturation arithmetic.

The idea itself is simple: keep the result inside the range of the destination type instead of allowing it to wrap or overflow.

The useful part is that we no longer need a separate custom helper for every operation.

Instead of writing something like:

auto add_clamped(...);
auto sub_clamped(...);
auto mul_clamped(...);

we can use:

std::saturating_add(...)
std::saturating_sub(...)
std::saturating_mul(...)
std::saturating_div(...)
std::saturating_cast(...)

Check the compiler support here: https://cppreference.com/cpp/compiler_support

For performance-sensitive code, it is also worth checking the generated assembly for your target architecture. Compiler Explorer is useful for this.

The main point is simple: when wrapping or signed overflow is not what you want, C++26 now gives you a standard way to say that directly.

Found this article helpful? Please Clap 👏 and follow for more C++ and system programming content.

Stop Writing Clamp Helpers: C++26’s Saturation Arithmetic was originally published in Towards Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.