Initial commit

Author: alii

.github/workflows/test.yml

@@ -0,0 +1,21 @@
+name: test
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: erlef/setup-beam@v1
+        with:
+          otp-version: '28'
+          gleam-version: '1.13.0'
+          rebar3-version: '3'
+          # elixir-version: "1"
+      - run: gleam deps download
+      - run: gleam test
+      - run: gleam format --check src test

.gitignore

@@ -0,0 +1,4 @@
+*.beam
+*.ez
+/build
+erl_crash.dump

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alistair Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,84 @@
+# gleam_manifold
+
+Gleam bindings to [Manifold](https://github.com/discord/manifold) - an Elixir library for fast message passing between BEAM nodes.
+
+## What is Manifold?
+
+Manifold is an Elixir library originally developed by Discord that optimizes sending the same message to many processes. Instead of sending messages sequentially (which can be slow with thousands of processes), Manifold uses a divide-and-conquer approach that distributes the work across multiple sender processes, achieving much better performance at scale.
+
+## Installation
+
+This library is intentionally not published to hex, because it depends on internal implementation details of Gleam's `erlang/process` module. If Gleam opens up the Subject type, we can implement this library in a more official way and publish to hex.
+
+For now, please depend on it as a git dependency in your `gleam.toml`:
+
+```toml
+[dependencies]
+gleam_manifold = { git = "[email protected]:otters/gleam_manifold.git", ref = "<commit hash>" }
+```
+
+## Usage
+
+### Type-safe sending to Subjects
+
+The primary way to use this library is with Gleam's type-safe `Subject` system:
+
+```gleam
+import gleam/erlang/process
+import gleam_manifold as manifold
+
+pub fn example() {
+  let subject = process.new_subject()
+
+  // Send a message through Manifold
+  manifold.send(subject, "Hello world")
+}
+```
+
+### Sending to PIDs
+
+For cases where you need to send to raw PIDs (not type-safe):
+
+```gleam
+import gleam_manifold as manifold
+
+pub fn send_to_pid(pid: process.Pid) {
+  manifold.send_pid(pid, "Hello")
+}
+```
+
+### Multicasting to multiple PIDs
+
+Send the same message to multiple processes at once:
+
+```gleam
+import gleam_manifold as manifold
+
+pub fn broadcast_join(pids: List(process.Pid), name: String) {
+  manifold.send_multi_pid(pids, "Hello, " <> name)
+}
+```
+
+## Implementation Notes
+
+### Internals Hack
+
+This library uses internals of Gleam's `erlang/process` implementation by unwrapping the opaque `Subject` type in Erlang. This is technically a hack since `Subject` is meant to be opaque, but it's necessary to extract the PID and reference tag needed for sending to Gleam's Subject type. The implementation pattern matches on the internal `{subject, Pid, Ref}` tuple structure in `gleam_manifold_ffi.erl`.
+
+### Current Limitations
+
+1. **No options parameter support**: The Elixir Manifold library supports an options parameter for tuning performance characteristics (like partition size). This Gleam wrapper doesn't currently expose these options, though this could be added in the future.
+
+2. **No named subjects support**: Named subjects (registered process names) are not currently supported. The library will fail with an assertion error if you try to use a named subject. This is fixable but hasn't been implemented yet.
+
+## Testing
+
+Run the tests with:
+
+```bash
+gleam test
+```
+
+## License
+
+See the LICENSE file in the repository.

gleam.toml

@@ -0,0 +1,15 @@
+name = "gleam_manifold"
+version = "1.0.0"
+
+description = "Gleam bindings to github.com/discord/manifold"
+licences = ["MIT"]
+repository = { type = "github", user = "otters", repo = "gleam_manifold" }
+links = [{ title = "Website", href = "https://otters.app" }]
+
+[dependencies]
+gleam_stdlib = ">= 0.44.0 and < 2.0.0"
+gleam_erlang = ">= 1.3.0 and < 2.0.0"
+manifold = ">= 1.6.0 and < 2.0.0"
+
+[dev-dependencies]
+gleeunit = ">= 1.0.0 and < 2.0.0"

manifest.toml

@@ -0,0 +1,15 @@
+# This file was generated by Gleam
+# You typically do not need to edit this file
+
+packages = [
+  { name = "gleam_erlang", version = "1.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_erlang", source = "hex", outer_checksum = "1124AD3AA21143E5AF0FC5CF3D9529F6DB8CA03E43A55711B60B6B7B3874375C" },
+  { name = "gleam_stdlib", version = "0.65.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "7C69C71D8C493AE11A5184828A77110EB05A7786EBF8B25B36A72F879C3EE107" },
+  { name = "gleeunit", version = "1.6.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "FDC68A8C492B1E9B429249062CD9BAC9B5538C6FBF584817205D0998C42E1DAC" },
+  { name = "manifold", version = "1.6.0", build_tools = ["mix"], requirements = [], otp_app = "manifold", source = "hex", outer_checksum = "F4028A840B903447E4A0A622E6EF64A755D4B9910EE05830CA40949C6568AC87" },
+]
+
+[requirements]
+gleam_erlang = { version = ">= 1.3.0 and < 2.0.0" }
+gleam_stdlib = { version = ">= 0.44.0 and < 2.0.0" }
+gleeunit = { version = ">= 1.0.0 and < 2.0.0" }
+manifold = { version = ">= 1.6.0 and < 2.0.0" }

src/gleam_manifold.gleam

@@ -0,0 +1,51 @@
+import gleam/erlang/process
+import gleam/erlang/reference
+
+pub fn send(subject: process.Subject(message), message: message) -> Nil {
+  let assert Ok(#(pid, ref)) = unwrap_subject(subject)
+    as "Named subjects are currently unsupported in gleam_manifold.send()"
+  manifold_send_subject(pid, #(ref, message))
+  Nil
+}
+
+/// You almost certainly do not want to use this. 
+/// Absolutely prefer to use the type-safe variant of
+/// this function `manifold.send(subject, message)`
+pub fn send_pid(pid: process.Pid, message: message) -> Nil {
+  manifold_send_raw(pid, message)
+  Nil
+}
+
+/// Call Manifold.send with a list of pids as the first argument, as
+/// is supported in Manifold
+/// 
+/// Sending multi does not support sending to subjects, because
+/// subjects themselves EACH have a unique tag along with them. The
+/// subject expects the tag to be included in the message itself, so
+/// this would mean that all subjects need to have the same tag, which is
+/// impossible because they are unique. You would have to use something
+/// like `process.select_other` to take advantage of receiving values
+/// with this function still within Gleam.
+pub fn send_multi_pid(pids: List(process.Pid), message: message) -> Nil {
+  manifold_send_multi(pids, message)
+  Nil
+}
+
+type DoNotLeak
+
+@external(erlang, "gleam_manifold_ffi", "unwrap_subject")
+fn unwrap_subject(
+  subject: process.Subject(message),
+) -> Result(#(process.Pid, reference.Reference), Nil)
+
+@external(erlang, "Elixir.Manifold", "send")
+fn manifold_send_subject(
+  pid: process.Pid,
+  message: #(reference.Reference, message),
+) -> DoNotLeak
+
+@external(erlang, "Elixir.Manifold", "send")
+fn manifold_send_raw(pid: process.Pid, message: message) -> DoNotLeak
+
+@external(erlang, "Elixir.Manifold", "send")
+fn manifold_send_multi(pid: List(process.Pid), message: message) -> DoNotLeak

src/gleam_manifold_ffi.erl

@@ -0,0 +1,7 @@
+-module(gleam_manifold_ffi).
+-export([unwrap_subject/1]).
+
+unwrap_subject({subject, Pid, Ref}) ->
+    {ok, {Pid, Ref}};
+unwrap_subject(_Subject) ->
+    {error, nil}.

test/gleam_manifold_test.gleam

@@ -0,0 +1,55 @@
+import gleam/erlang/process
+import gleam_manifold as manifold
+import gleeunit
+
+pub fn main() -> Nil {
+  gleeunit.main()
+}
+
+pub fn simple_test() {
+  let subject = process.new_subject()
+  process.spawn(fn() { manifold.send(subject, "Hello world") })
+  assert process.receive(subject, 100) == Ok("Hello world")
+}
+
+pub fn many_pids_test() {
+  let subject = process.new_subject()
+
+  let proc = fn() {
+    let selector = process.new_selector() |> process.select_other(identity)
+    let assert Ok(result) = process.selector_receive(selector, 5)
+    process.send(subject, result)
+  }
+
+  let a = process.spawn(proc)
+  let b = process.spawn(proc)
+
+  manifold.send_pid(a, "hello from a")
+  manifold.send_pid(b, "hello from b")
+
+  assert process.receive(subject, 5) == Ok("hello from a")
+  assert process.receive(subject, 5) == Ok("hello from b")
+  assert process.receive(subject, 5) == Error(Nil)
+}
+
+pub fn multi_pids_test() {
+  let subject = process.new_subject()
+
+  let proc = fn() {
+    let selector = process.new_selector() |> process.select_other(identity)
+    let assert Ok(result) = process.selector_receive(selector, 5)
+    process.send(subject, result)
+  }
+
+  let a = process.spawn(proc)
+  let b = process.spawn(proc)
+
+  manifold.send_multi_pid([a, b], "hello from both")
+
+  assert process.receive(subject, 5) == Ok("hello from both")
+  assert process.receive(subject, 5) == Ok("hello from both")
+  assert process.receive(subject, 5) == Error(Nil)
+}
+
+@external(erlang, "gleam_erlang_ffi", "identity")
+fn identity(x: a) -> b