-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Affects: io7m-com/.github#2
- Loading branch information
Showing
14 changed files
with
122 additions
and
534 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
Submodule .jenkins
deleted from
3213e2
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
20 changes: 0 additions & 20 deletions
20
com.io7m.jserial.documentation/src/main/assembly/documentation.xml
This file was deleted.
Oops, something went wrong.
30 changes: 0 additions & 30 deletions
30
...o7m.jserial.documentation/src/main/java/com/io7m/jserial/documentation/Documentation.java
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.