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 project as follows:

npm i @rbxts/value-holders

Wally

Wally users can install this package by adding the following line to their Wally.toml under [dependencies]:

ValueHolders = "bytebit/[email protected]"

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 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.

Documentation

Documentation can be found here, is included in the TypeScript files directly, and was generated using TypeDoc.

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.

import { IValueHolder, IReadonlyValueHolder, ValueHolder } from "@rbxts/value-holders";

export class Writer {
  public readonly valueHolder: IReadonlyValueHolder<number>;

  private readonly internalValueHolder: IValueHolder<number>;

  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<number>) {
    valueHolder.valueChanged.Connect(newValue => print("New value is: " + newValue));
  }
}

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.

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<number>) {
    valueHolder.valueChanged.Connect(newValue => print("New value is: " + newValue));
  }
}

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
}