https://github.com/bytebit-org/roblox-valueholders
A module for passing any values around by sharing a pointer, as well as allowing consumers to subscribe to changes and allowing authors to hold locks on changing the value.
https://github.com/bytebit-org/roblox-valueholders
Last synced: 18 days ago
JSON representation
A module for passing any values around by sharing a pointer, as well as allowing consumers to subscribe to changes and allowing authors to hold locks on changing the value.
- Host: GitHub
- URL: https://github.com/bytebit-org/roblox-valueholders
- Owner: Bytebit-Org
- License: mit
- Created: 2022-03-22T16:29:03.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2022-04-05T05:19:03.000Z (almost 4 years ago)
- Last Synced: 2025-01-30T03:18:26.575Z (12 months ago)
- Language: TypeScript
- Size: 345 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Value Holders
Value Holders is a module for passing any values around by sharing a pointer, as well as allowing consumers to subscribe to changes and allowing authors to hold locks on changing the value.
## Installation
### roblox-ts
Simply install to your [roblox-ts](https://roblox-ts.com/) project as follows:
```
npm i @rbxts/value-holders
```
### Wally
[Wally](https://github.com/UpliftGames/wally/) users can install this package by adding the following line to their `Wally.toml` under `[dependencies]`:
```
ValueHolders = "bytebit/value-holders@1.0.7"
```
Then just run `wally install`.
### From model file
Model files are uploaded to every release as `.rbxmx` files. You can download the file from the [Releases page](https://github.com/Bytebit-Org/roblox-ValueHolders/releases) and load it into your project however you see fit.
### From model asset
New versions of the asset are uploaded with every release. The asset can be added to your Roblox Inventory and then inserted into your Place via Toolbox by getting it [here.](https://www.roblox.com/library/9170323611/Value-Holders-Package)
## Documentation
Documentation can be found [here](https://github.com/Bytebit-Org/roblox-ValueHolders/tree/master/docs), is included in the TypeScript files directly, and was generated using [TypeDoc](https://typedoc.org/).
## Examples
### Standard IValueHolder and a Readonly consumer
Here's an example of using a standard `IValueHolder` with one class, `Writer`, that contains the value and exposes it publicly as an `IReadonlyValueHolder` and one class, `Reader`, that only reads from the `IValueHolder` by using the `IReadonlyValueHolder` reference (in the TypeScript example). The actual value isn't very important for the purposes of this example, so we'll just have `Writer` update the value once every second.
roblox-ts example
```ts
import { IValueHolder, IReadonlyValueHolder, ValueHolder } from "@rbxts/value-holders";
export class Writer {
public readonly valueHolder: IReadonlyValueHolder;
private readonly internalValueHolder: IValueHolder;
public constructor() {
this.internalValueHolder = new ValueHolder(0);
this.valueHolder = this.internalValueHolder;
this.incrementValueEverySecond();
}
private incrementValueEverySecond() {
while (true) {
task.wait(1);
valueHolder.updateValue(currentValue => currentValue + 1);
}
}
}
export class Reader {
public constructor(writer: Writer) {
this.printEveryValueUpdate(writer.valueHolder);
}
private printEveryValueUpdate(valueHolder: IReadonlyValueHolder) {
valueHolder.valueChanged.Connect(newValue => print("New value is: " + newValue));
}
}
```
Luau example
```lua
local ValueHolder = require(path.to.modules["value-holders"]).ValueHolder
local Writer = {}
Writer.__index = Writer
local WriterConstructor = {}
function WriterConstructor.new()
local self = {}
setmetatable(self, Writer)
self.valueHolder = ValueHolder.create(0)
_incrementValueEverySecond(self)
return self
end
function _incrementValueEverySecond(self)
while true do
task.wait(1)
self.valueHolder:updateValue(function (currentValue)
return currentValue + 1
end)
end
end
local Reader = {}
Reader.__index = Reader
local ReaderConstructor = {}
function ReaderConstructor.new(writer)
local self = {}
setmetatable(self, Reader)
_printEveryValueUpdate(self, writer.valueHolder)
return self
end
function _printEveryValueUpdate(self, valueHolder)
valueHolder.valueChanged:Connect(function (newValue)
print("New value is: ", newValue)
end)
end
return {
Writer = WriterConstructor,
Reader = ReaderConstructor
}
```
### Two writers fighting over one ILockableValueHolder instance
The `ILockableValueHolder` interface is meant to enable some writers to shut off access to further writes from other potential writers. In this example, there will be a class that locks the value holder via a public method and another class that tries to set the value to 0 every second. Whenever the value is locked, the first class will increment the value every second. As in the previous example, we'll also have a Reader that just prints the value every time that it changes.
roblox-ts example
```ts
import { ILockableValueHolder, IReadonlyValueHolder, LockableValueHolder } from "@rbxts/value-holders";
// not going to use this but just for example purposes
const exampleLockableValueHolder = LockableValueHolder.create(0);
export class LockedIncrementingWriter {
private lockKey: object | undefined = undefined;
public constructor(private readonly lockableValueHolder: ILockableValueHolder) {
this.incrementValueEverySecond();
}
public takeLock() {
if (this.lockKey !== undefined) {
return;
}
this.lockKey = this.lockableValueHolder.tryTakeLock();
}
public releaseLock() {
if (this.lockKey !== undefined) {
return;
}
this.lockableValueHolder.releaseLock(this.lockKey);
this.lockKey = undefined;
}
private incrementValueEverySecond() {
while (true) {
task.wait(1);
if (lockableValueHolder.isLocked()) {
lockableValueHolder.updateValue(
currentValue => currentValue + 1,
this.lockKey);
}
}
}
}
export class ZeroWriter {
public constructor(private readonly lockableValueHolder: ILockableValueHolder) {
this.setValueToZeroEverySecond();
}
private setValueToZeroEverySecond() {
while (true) {
task.wait(1);
if (!lockableValueHolder.isLocked()) {
// If the code did not first check whether the value holder was locked,
// then this line would error
lockableValueHolder.setValue(0);
}
}
}
}
export class Reader {
public constructor(valueHolder: IReadonlyValueHolder) {
this.printEveryValueUpdate(valueHolder);
}
private printEveryValueUpdate(valueHolder: IReadonlyValueHolder) {
valueHolder.valueChanged.Connect(newValue => print("New value is: " + newValue));
}
}
```
Luau example
```lua
local LockableValueHolder = require(path.to.modules["value-holders"]).LockableValueHolder
-- not going to use this but just for example purposes
local exampleLockableValueHolder = LockableValueHolder.create(0);
local LockedIncrementingWriter = {}
LockedIncrementingWriter.__index = LockedIncrementingWriter
local LockedIncrementingWriterConstructor = {}
function LockedIncrementingWriterConstructor.new(lockableValueHolder)
local self = {}
setmetatable(self, LockedIncrementingWriter)
self._lockableValueHolder = lockableValueHolder
_incrementValueEverySecond(self)
return self
end
function LockedIncrementingWriter:takeLock()
if self._lockKey then
return
end
self._lockKey = self._lockableValueHolder:tryTakeLock();
end
function LockedIncrementingWriter:releaseLock()
if self._lockKey then
return
end
self._lockableValueHolder:releaseLock(self._lockKey);
self._lockKey = nil;
end
function _incrementValueEverySecond(self)
while true do
task.wait(1)
if self._lockableValueHolder:isLocked() then
self._lockableValueHolder:updateValue(function (currentValue)
return currentValue + 1
end, self._lockKey)
end
end
end
local ZeroWriter = {}
ZeroWriter.__index = ZeroWriter
local ZeroWriterConstructor = {}
function ZeroWriterConstructor.new(lockableValueHolder)
local self = {}
setmetatable(self, ZeroWriter)
self._lockableValueHolder = lockableValueHolder
_setValueToZeroEverySecond(self)
return self
end
function _setValueToZeroEverySecond(self)
while true do
task.wait(1)
if not self._lockableValueHolder:isLocked() then
-- If the code did not first check whether the value holder was locked,
-- then this line would error
self._lockableValueHolder:setValue(0)
end
end
end
local Reader = {}
Reader.__index = Reader
local ReaderConstructor = {}
function ReaderConstructor.new(valueHolder)
local self = {}
setmetatable(self, Reader)
_printEveryValueUpdate(self, valueHolder)
return self
end
function _printEveryValueUpdate(self, valueHolder)
valueHolder.valueChanged:Connect(function (newValue)
print("New value is: ", newValue)
end)
end
return {
LockedIncrementingWriter = LockedIncrementingWriterConstructor,
ZeroWriter = ZeroWriterConstructor,
Reader = ReaderConstructor
}
```