Skip to content

Commit

Permalink
Eliminate jstructural
Browse files Browse the repository at this point in the history
  • Loading branch information
io7m committed May 4, 2024
1 parent 7cb0adc commit e64d1b1
Show file tree
Hide file tree
Showing 14 changed files with 122 additions and 534 deletions.
3 changes: 0 additions & 3 deletions .gitmodules
Original file line number Diff line number Diff line change
@@ -1,3 +0,0 @@
[submodule ".jenkins"]
path = .jenkins
url = http://www.github.com/io7m/jenkinsfiles
1 change: 0 additions & 1 deletion .jenkins
Submodule .jenkins deleted from 3213e2
57 changes: 57 additions & 0 deletions README.in
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@

## jserial

A Java implementation of enhanced
[serial number arithmetic](https://en.wikipedia.org/wiki/Serial_number_arithmetic).

## Features

* 8-bit serial number arithmetic
* 16-bit serial number arithmetic
* 24-bit serial number arithmetic
* 32-bit serial number arithmetic
* 40-bit serial number arithmetic
* 48-bit serial number arithmetic
* 56-bit serial number arithmetic
* 62-bit serial number arithmetic
* High coverage test suite.
* [OSGi-ready](https://www.osgi.org/)
* [JPMS-ready](https://en.wikipedia.org/wiki/Java_Platform_Module_System)
* ISC license.

## Motivation

Many communications protocols use fixed-sized fields to store
[sequence numbers](https://en.wikipedia.org/wiki/Sequence_number).
Unfortunately, given that the fields are of a fixed size, it is inevitable
that the sequence numbers will eventually reach the maximum possible value
that can be stored in fields of that size and, using unsigned arithmetic,
will then wrap around to `0`. This can cause serious problems for systems
tracking sequence numbers as the numbers are no longer monotonically
increasing.

Using [serial number arithmetic](https://en.wikipedia.org/wiki/Serial_number_arithmetic),
it's possible to have sequence numbers that can wrap around indefinitely, but
that the application can still treat as being conceptually monotonically
increasing.

## Usage

Choose an implementation based on the number of bits used to store serial
numbers in your intended protocol. Most protocols will want to use 32 bits:

```
var s = SerialNumber32.get();
```

Given a starting number `x`, get the next number in the sequence according
to serial number arithmetic at the specified implementation size:

```
var y = s.add(x, 1L);
```

The `SerialNumberLongType` and `SerialNumberIntType` interfaces expose
numerous methods to increment and compare numbers. In the above code, the
value `y` can be compared with `x`, and the `compare` implementation will
indicate that `y` is greater than `x`, even if `y` has wrapped around to zero.
58 changes: 58 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,61 @@ jserial
| OpenJDK (Temurin) LTS | Linux | [![Build (OpenJDK (Temurin) LTS, Linux)](https://img.shields.io/github/actions/workflow/status/io7m-com/jserial/main.linux.temurin.lts.yml)](https://www.github.com/io7m-com/jserial/actions?query=workflow%3Amain.linux.temurin.lts)|
| OpenJDK (Temurin) Current | Windows | [![Build (OpenJDK (Temurin) Current, Windows)](https://img.shields.io/github/actions/workflow/status/io7m-com/jserial/main.windows.temurin.current.yml)](https://www.github.com/io7m-com/jserial/actions?query=workflow%3Amain.windows.temurin.current)|
| OpenJDK (Temurin) LTS | Windows | [![Build (OpenJDK (Temurin) LTS, Windows)](https://img.shields.io/github/actions/workflow/status/io7m-com/jserial/main.windows.temurin.lts.yml)](https://www.github.com/io7m-com/jserial/actions?query=workflow%3Amain.windows.temurin.lts)|

## jserial

A Java implementation of enhanced
[serial number arithmetic](https://en.wikipedia.org/wiki/Serial_number_arithmetic).

## Features

* 8-bit serial number arithmetic
* 16-bit serial number arithmetic
* 24-bit serial number arithmetic
* 32-bit serial number arithmetic
* 40-bit serial number arithmetic
* 48-bit serial number arithmetic
* 56-bit serial number arithmetic
* 62-bit serial number arithmetic
* High coverage test suite.
* [OSGi-ready](https://www.osgi.org/)
* [JPMS-ready](https://en.wikipedia.org/wiki/Java_Platform_Module_System)
* ISC license.

## Motivation

Many communications protocols use fixed-sized fields to store
[sequence numbers](https://en.wikipedia.org/wiki/Sequence_number).
Unfortunately, given that the fields are of a fixed size, it is inevitable
that the sequence numbers will eventually reach the maximum possible value
that can be stored in fields of that size and, using unsigned arithmetic,
will then wrap around to `0`. This can cause serious problems for systems
tracking sequence numbers as the numbers are no longer monotonically
increasing.

Using [serial number arithmetic](https://en.wikipedia.org/wiki/Serial_number_arithmetic),
it's possible to have sequence numbers that can wrap around indefinitely, but
that the application can still treat as being conceptually monotonically
increasing.

## Usage

Choose an implementation based on the number of bits used to store serial
numbers in your intended protocol. Most protocols will want to use 32 bits:

```
var s = SerialNumber32.get();
```

Given a starting number `x`, get the next number in the sequence according
to serial number arithmetic at the specified implementation size:

```
var y = s.add(x, 1L);
```

The `SerialNumberLongType` and `SerialNumberIntType` interfaces expose
numerous methods to increment and compare numbers. In the above code, the
value `y` can be compared with `x`, and the `compare` implementation will
indicate that `y` is greater than `x`, even if `y` has wrapped around to zero.

215 changes: 0 additions & 215 deletions com.io7m.jserial.documentation/pom.xml

This file was deleted.

20 changes: 0 additions & 20 deletions com.io7m.jserial.documentation/src/main/assembly/documentation.xml

This file was deleted.

This file was deleted.

Loading

0 comments on commit e64d1b1

Please sign in to comment.