From c3d7e9d0813fff3e05e7a8ad8a7fa232f28a50b7 Mon Sep 17 00:00:00 2001 From: Graham Date: Sat, 15 Aug 2020 11:28:08 +0100 Subject: [PATCH] Add reference counting documentation Signed-off-by: Graham --- share/doc/reference-counting.md | 47 +++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 share/doc/reference-counting.md diff --git a/share/doc/reference-counting.md b/share/doc/reference-counting.md new file mode 100644 index 0000000000..f50aa262e1 --- /dev/null +++ b/share/doc/reference-counting.md @@ -0,0 +1,47 @@ +# Reference counting + +[Netty][netty] uses reference counting for some objects, such as `ByteBuf`s. +The Netty documentation explains its +[use of reference counting][netty-ref-counting] in more detail. + +OpenRS2 has an extension method that automatically wraps a block of code in a +`try`/`finally` block, calling `release()` in the `finally` block. It is very +similar to Kotlin's extension method for `close()`ing `Closeable`s (and in fact +has the same name: `use`). + +A typical pattern for allocating and then releasing a `ByteBuf` using this +method is: + +```kt +alloc.buffer().use { buf -> + // use buf here +} +``` + +In OpenRS2, a method that consumes a `ByteBuf` is generally not responsible for +releasing it - the caller is. This provides more flexibility, as the caller +might want to continue reading from the buffer. (For example, after calling +`Js5Compression.uncompress()`, the caller will probably want to read the 2 byte +version trailer from the same buffer.) + +For obvious reasons, a method that produces a `ByteBuf` is generally not +responsible for releasing it - again, the caller is. However, arranging for the +`ByteBuf` to be freed if an exception occurs between the `ByteBuf` being +allocated and returned is tricky. The following pattern is useful for correctly +releasing/retaining the buffer depending on whether an exception occurs or not: + +```kt +alloc.buffer().use { buf -> + // write to buf here + return buf.retain() +} +``` + +If any of the code prior to the `return` fails, the buffer is released. + +If the `return` is reached, no more exceptions can occur. The reference count +is increased to counteract the `finally` block decreasing it, such that by the +time the buffer reaches the caller its reference count is 1. + +[netty]: https://netty.io/ +[netty-ref-counting]: https://netty.io/wiki/reference-counted-objects.html