From 02d2261768f227f8e7d3229a19a9b70fdac334d0 Mon Sep 17 00:00:00 2001 From: prms-magnet Date: Sun, 16 Aug 2026 13:16:53 -0700 Subject: [PATCH 1/2] docs: rebrand project-facing documentation as Luwu --- .github/ISSUE_TEMPLATE/config.yml | 4 ++-- CONTRIBUTING.md | 24 +++++++++++------------ MAINTAINERS.md | 2 +- README.md | 32 ++++++++++++++++--------------- SECURITY.md | 8 ++++---- 5 files changed, 36 insertions(+), 34 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index c7fb782a..3607dd9a 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,5 @@ blank_issues_enabled: false contact_links: - name: Questions - url: https://github.com/luau-lang/luau/discussions - about: Please use GitHub Discussions if you have questions or need help. + url: https://discord.gg/3MJ37CFNWh + about: Please join the Luwu Discord server if you have questions or need help. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d9ba7b0a..045aac02 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,21 +1,21 @@ -Thanks for deciding to contribute to Luau! These guidelines will try to help make the process painless and efficient. +Thanks for deciding to contribute to Luwu! These guidelines will help make the process painless and efficient. ## Questions -If you have a question regarding the language usage/implementation, please [use GitHub discussions](https://github.com/luau-lang/luau/discussions). +If you have a question about using or implementing the language, please join the [Luwu Discord server](https://discord.gg/3MJ37CFNWh). Some questions just need answers, but it's nice to keep them for future reference in case other people want to know the same thing. Some questions help improve the language, implementation or documentation by inspiring future changes. ## Documentation -A [separate site repository](https://github.com/luau-lang/site) hosts the language documentation, which is accessible on https://luau.org. -Changes to this documentation that improve clarity, fix grammatical issues, explain aspects that haven't been explained before and the like are warmly welcomed. +Luwu is based on Luau, so the [upstream Luau documentation](https://luau.org) remains a useful reference for compatible behavior. Luwu-specific proposals and changes are documented in the [extra RFCs folder](/rfcx/). +Changes that improve clarity, fix grammatical issues, or explain Luwu-specific behavior are warmly welcomed. Please feel free to [create a pull request](https://help.github.com/articles/about-pull-requests/) to improve our documentation. Note that at this point the documentation is English-only. ## Bugs -If the language implementation doesn't compile on your system, compiles with warnings, doesn't seem to run correctly for your code or if anything else is amiss, please [open a GitHub issue](https://github.com/luau-lang/luau/issues/new). +If the language implementation doesn't compile on your system, compiles with warnings, doesn't seem to run correctly for your code or if anything else is amiss, please [open a GitHub issue](https://github.com/mluau/luwu/issues/new). It helps if you note the Git revision issue happens in, the version of your compiler for compilation issues, and a reproduction case for runtime bugs. Of course, feel free to [create a pull request](https://help.github.com/articles/about-pull-requests/) to fix the bug yourself. @@ -23,12 +23,12 @@ Of course, feel free to [create a pull request](https://help.github.com/articles ## Features If you're thinking of adding a new feature to the language, library, analysis tools, etc., please *don't* start by submitting a pull request. -The Luau team has internal priorities and a roadmap that may or may not align with specific features, so before starting to work on a feature, please submit an issue describing the missing feature that you'd like to add. +Discuss the idea in the `#features` channel on the [Luwu Discord server](https://discord.gg/3MJ37CFNWh) before starting implementation so the community can refine the proposal and identify potential conflicts. -For features that result in an observable change to the language's syntax or semantics, you'll need to [create an RFC](https://github.com/luau-lang/rfcs/blob/master/README.md) to make sure that the feature is needed and well-designed. +For features that result in an observable change to the language's syntax or semantics, create an RFC in the [extra RFCs folder](/rfcx/) using the provided [template](/rfcx/TEMPLATE.md). Follow the process in the [extra RFC guidelines](/rfcx/README.md), including the implementation, feature flag, and maintainer requirements. -Finally, please note that Luau tries to carry a minimal feature set. All features must be evaluated not just for the benefits that they provide, but also for the downsides/costs in terms of language simplicity, maintainability, cross-feature interaction, etc. -As such, feature requests may not be accepted even if a comprehensive RFC is written - don't expect Luau to gain a feature just because another programming language has it. +Luwu is willing to evolve independently from upstream Luau, but every feature must still be evaluated for language simplicity, maintainability, performance, and cross-feature interactions. +Feature requests may not be accepted even if a comprehensive RFC is written; the benefits need to justify the costs to the language and its community. We generally apply a standard similar to the C\# team's famous [Minus 100 Points](https://learn.microsoft.com/en-us/archive/blogs/ericgu/minus-100-points). ## Code style @@ -36,7 +36,7 @@ We generally apply a standard similar to the C\# team's famous [Minus 100 Points Contributions to this project are expected to follow the existing code style. `.clang-format` file mostly defines syntactic styling rules (you can run `make format` to format the code accordingly). -As for naming conventions, most Luau components use `lowerCamelCase` for variables and functions, `UpperCamelCase` for types and enums, `kCamelCase` for global constants and `SCARY_CASE` for macros. +As for naming conventions, most Luwu components use `lowerCamelCase` for variables and functions, `UpperCamelCase` for types and enums, `kCamelCase` for global constants and `SCARY_CASE` for macros. Within the VM component, the code style is different - we expect `lua_` or `luaX_` prefix for functions that are public or used across different VM files, camel case isn't used and macros are often using lowercase. @@ -49,13 +49,13 @@ When making code changes please try to make sure they are covered by an existing ## Performance -One of the central features of Luau is performance; our runtime in particular is heavily optimized for high performance and low memory consumption, and code is generally carefully tuned to result in close-to-optimal assembly for x64 and AArch64 architectures. The analysis code is not optimized to the same level of detail, but performance is still very important to make sure that we can support interactive IDE features. +One of the central features of Luwu is performance; our runtime in particular is heavily optimized for high performance and low memory consumption, and code is generally carefully tuned to result in close-to-optimal assembly for x64 and AArch64 architectures. The analysis code is not optimized to the same level of detail, but performance is still very important to make sure that we can support interactive IDE features. As such, it's important to make sure that the changes, including bug fixes, improve (or at least do not regress) performance. For the VM, this can be validated by running `bench/bench.py` on two binaries built in Release mode, before and after the changes. Note that our benchmark coverage is not complete, and in some cases, additional performance testing will be necessary to determine if the change can be merged. ## Feature flags -For large bug fixes or features that apply to the Luau components and not just the CLI tools, we may ask that you introduce a feature flag to gate your changes. The feature flags use `LUAU_FASTFLAG` macro family defined in `Luau/Common.h` and allow us to ensure that the change can be safely shipped, enabled, and rolled back on the Roblox platform when the change makes it into our production codebase. The tests run the code with flags in their default state and enabled state as well to ensure correctness. +For large bug fixes or features that apply to the Luwu components and not just the CLI tools, we may ask that you introduce a feature flag to gate your changes. The feature flags use the `LUAU_FASTFLAG` macro family defined in `Luau/Common.h` and allow changes to be enabled and rolled back safely. The tests run the code with flags in their default and enabled states to ensure correctness. ## Licensing diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 73a74bfa..1bc81ede 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -10,7 +10,7 @@ - LuauFatCClosure: @cheesycod - LuauManagedReferences2: @cheesycod - LuauFunctionUnusedRecursiveLinting, LuauBetterPackAndVariadicMismatchErrors, LuauIndexerModifierMismatchErrors, LuauPropertyModifierMismatchErrors: @MabMabMabMabMab (undercols) authored by @PhoenixWhitefire (merged from upstream) -- LuauBetterMissingPropertiesTypeError, LuauFunctionUnusedRecursiveLinting: @MabMabMabMabMab and @deviaze (authored by nnullcolumn, who is not an mluau/luau maintainer; merged from upstream) +- LuauBetterMissingPropertiesTypeError, LuauFunctionUnusedRecursiveLinting: @MabMabMabMabMab and @deviaze (authored by nnullcolumn, who is not an mluau/luwu maintainer; merged from upstream) ## Other diff --git a/README.md b/README.md index 6426ad4c..94b62937 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,19 @@ -Luau ![CI](https://github.com/mluau/luau/actions/workflows/build.yml/badge.svg) [![codecov](https://codecov.io/gh/mluau/luau/branch/master/graph/badge.svg)](https://codecov.io/gh/mluau/luau) +Luwu ![CI](https://github.com/mluau/luwu/actions/workflows/build.yml/badge.svg) [![codecov](https://codecov.io/gh/mluau/luwu/branch/master/graph/badge.svg)](https://codecov.io/gh/mluau/luwu) ==== -Luau (lowercase u, /ˈlu.aʊ/) is a fast, small, safe, gradually typed embeddable scripting language derived from [Lua](https://lua.org). +Luwu is a fast, small, safe, gradually typed embeddable scripting language based on [Luau](https://luau.org). -This is a community fork of Luau intended to provide a more featureful, helpful, and community-driven experience for general purpose, open source development of the language. +Luwu is a community-led fork intended to provide a more featureful and helpful experience for general-purpose, open-source language development. It will evolve with features, syntax, and semantics that may not align with upstream Luau. -For more information about this fork, how to contribute, and help us name our new language based off of Luau (but different!), please join our discord server [hina & ferris](https://discord.gg/3MJ37CFNWh). +Luwu is backwards compatible with Luau up to and including version 0.730, with possible exceptions for `export local` and Luau's unreleased integer feature as those areas are improved in Luwu. + +For more information about Luwu and how to contribute, please join our Discord server [hina & ferris](https://discord.gg/3MJ37CFNWh). Credit for the name goes to @Crazyblox! For RFCs and changes to the language, please see the [RFCs folder](/rfcx/). To propose new features, discuss them in our `#features` channel on Discord. # Usage -Luau is an embeddable programming language, but it also comes with two command-line tools by default, `luau` and `luau-analyze`. +Luwu is an embeddable programming language, but it also comes with two command-line tools by default, `luau` and `luau-analyze`. `luau` is a command-line REPL and can also run input files. Note that REPL runs in a sandboxed environment and as such doesn't have access to the underlying file system except for ability to `require` modules. @@ -19,9 +21,9 @@ Luau is an embeddable programming language, but it also comes with two command-l # Installation -You can install and run Luau by downloading the compiled binaries from [a recent release](https://github.com/luau-lang/luau/releases); note that `luau` and `luau-analyze` binaries from the archives will need to be added to PATH or copied to a directory like `/usr/local/bin` on Linux/macOS. +You can install and run Luwu by downloading the compiled binaries from [a recent release](https://github.com/mluau/luwu/releases); note that `luau` and `luau-analyze` binaries from the archives will need to be added to PATH or copied to a directory like `/usr/local/bin` on Linux/macOS. -Alternatively, you can use one of the packaged distributions (note that these are not maintained by Luau development team): +Alternatively, upstream Luau is available from the packaged distributions below. These packages are not maintained by the Luwu development team and may not match Luwu's Luau 0.730 compatibility baseline: - macOS: [Install Homebrew](https://docs.brew.sh/Installation) and run `brew install luau` - Arch Linux: Luau has been added to the official Arch Linux packages repository under the extras repository (see [``luau``](https://archlinux.org/packages/extra/x86_64/luau/)), simply install using ``pacman``: ``pacman -Syu luau`` @@ -32,7 +34,7 @@ After installing, you will want to validate the installation was successful by r ## Building -On all platforms, you can use CMake to run the following commands to build Luau binaries from source: +On all platforms, you can use CMake to run the following commands to build Luwu binaries from source: ```sh mkdir cmake && cd cmake @@ -47,7 +49,7 @@ Alternatively, on Linux and macOS, you can also use `make`: make config=release luau luau-analyze ``` -To integrate Luau into your CMake application projects as a library, at the minimum, you'll need to depend on `Luau.Compiler` and `Luau.VM` projects. From there you need to create a new Luau state (using Lua 5.x API such as `lua_newstate`), compile source to bytecode and load it into the VM like this: +To integrate Luwu into your CMake application projects as a library, at the minimum, you'll need to depend on the `Luau.Compiler` and `Luau.VM` projects. From there you need to create a new state (using a Lua 5.x API such as `lua_newstate`), compile source to bytecode, and load it into the VM like this: ```cpp // needs lua.h and luacode.h @@ -60,24 +62,24 @@ if (result == 0) return 1; /* return chunk main function */ ``` -For more details about the use of the host API, you currently need to consult [Lua 5.x API](https://www.lua.org/manual/5.1/manual.html#3). Luau closely tracks that API but has a few deviations, such as the need to compile source separately (which is important to be able to deploy VM without a compiler), and the lack of `__gc` support (use `lua_newuserdatadtor` instead). +For more details about the use of the host API, you currently need to consult the [Lua 5.x API](https://www.lua.org/manual/5.1/manual.html#3). Luwu inherits Luau's close alignment with that API, including a few deviations such as the need to compile source separately (which is important for deploying the VM without a compiler) and the lack of `__gc` support (use `lua_newuserdatadtor` instead). To gain advantage of many performance improvements, it's highly recommended to use the `safeenv` feature, which sandboxes individual scripts' global tables from each other, and protects builtin libraries from monkey-patching. For this to work, you must call `luaL_sandbox` on the global state and `luaL_sandboxthread` for each new script's execution thread. # Testing -Luau has an internal test suite; in CMake builds, it is split into two targets, `Luau.UnitTest` (for the bytecode compiler and type checker/linter tests) and `Luau.Conformance` (for the VM tests). The unit tests are written in C++, whereas the conformance tests are largely written in Luau (see `tests/conformance`). +Luwu has an internal test suite; in CMake builds, it is split into two targets, `Luau.UnitTest` (for the bytecode compiler and type checker/linter tests) and `Luau.Conformance` (for the VM tests). The unit tests are written in C++, whereas the conformance tests are largely written in Luwu (see `tests/conformance`). Makefile builds combine both into a single target that can be run via `make test`. # Dependencies -Luau uses C++ as its implementation language. The runtime requires C++11, while the compiler and analysis components require C++17. It should build without issues using Microsoft Visual Studio 2017 or later, or gcc-7 or clang-7 or later. +Luwu uses C++ as its implementation language. The runtime requires C++11, while the compiler and analysis components require C++17. It should build without issues using Microsoft Visual Studio 2017 or later, or gcc-7 or clang-7 or later. -Other than the STL/CRT, Luau library components don't have external dependencies. The test suite depends on the [doctest](https://github.com/onqtam/doctest) testing framework, and the REPL command-line depends on [isocline](https://github.com/daanx/isocline). +Other than the STL/CRT, Luwu library components don't have external dependencies. The test suite depends on the [doctest](https://github.com/onqtam/doctest) testing framework, and the REPL command-line depends on [isocline](https://github.com/daanx/isocline). # License -Luau implementation is distributed under the terms of [MIT License](https://github.com/luau-lang/luau/blob/master/LICENSE.txt). It is based on the Lua 5.x implementation, also under the MIT License. +The Luwu implementation is distributed under the terms of the [MIT License](LICENSE.txt). It is based on [Luau](https://github.com/luau-lang/luau), which is based on the Lua 5.x implementation; both are also distributed under the MIT License. -When Luau is integrated into external projects, we ask that you honor the license agreement and include Luau attribution into the user-facing product documentation. Attribution making use of the [Luau logo](https://github.com/luau-lang/site/blob/master/logo.svg) is also encouraged when reasonable. +When Luwu is integrated into external projects, please honor the included license notices and preserve attribution to Luwu, Luau, and Lua. diff --git a/SECURITY.md b/SECURITY.md index 0639f314..06a57922 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,14 +1,14 @@ # Security Guarantees -Luau provides a safe sandbox that scripts can not escape from, short of vulnerabilities in custom C functions exposed by the host. This includes the virtual machine, builtin libraries and native code generation facilities. +Luwu provides a safe sandbox that scripts can not escape from, short of vulnerabilities in custom C functions exposed by the host. This includes the virtual machine, builtin libraries and native code generation facilities. Any source code can not result in memory safety errors or crashes during its compilation or execution. Violations of memory safety are considered vulnerabilities. -Note that Luau does not provide termination guarantees - some code may exhaust CPU or RAM resources on the system during compilation or execution. +Note that Luwu does not provide termination guarantees - some code may exhaust CPU or RAM resources on the system during compilation or execution. -The runtime expects valid bytecode as an input. Feeding bytecode that was not produced by Luau compiler into the VM is not supported, and +The runtime expects valid bytecode as an input. Feeding bytecode that was not produced by the Luwu compiler into the VM is not supported, and doesn't come with any security guarantees; make sure to sign and/or encrypt the bytecode when it crosses a network or file system boundary to avoid tampering. # Reporting a Vulnerability -Please DM a language maintainer on [our Discord](https://discord.gg/3MJ37CFNWh) or email deviaze at `dev@deviaze.com` to report a security vulnerability in `mluau/luau`. +Please DM a language maintainer on [our Discord](https://discord.gg/3MJ37CFNWh) or email deviaze at `dev@deviaze.com` to report a security vulnerability in `mluau/luwu`. From 6d7bd759b89b621e0b7b53c4616ba2ba4c810a10 Mon Sep 17 00:00:00 2001 From: prms-magnet Date: Sun, 16 Aug 2026 13:17:06 -0700 Subject: [PATCH 2/2] docs(rfcx): rebrand RFC documentation as Luwu --- rfcx/README.md | 6 +++--- rfcx/api-luau-managed-refs.md | 23 ----------------------- rfcx/api-luwu-managed-refs.md | 23 +++++++++++++++++++++++ rfcx/external-buffers.md | 12 ++++++------ rfcx/external-strings.md | 16 ++++++++-------- rfcx/fat-c-closures.md | 10 +++++----- rfcx/function-default-arguments.md | 23 +++++++++++------------ rfcx/none.md | 6 +++--- rfcx/thread-statechange-hook.md | 6 +++--- 9 files changed, 62 insertions(+), 63 deletions(-) delete mode 100644 rfcx/api-luau-managed-refs.md create mode 100644 rfcx/api-luwu-managed-refs.md diff --git a/rfcx/README.md b/rfcx/README.md index 97f5a9cb..a63990f2 100644 --- a/rfcx/README.md +++ b/rfcx/README.md @@ -1,10 +1,10 @@ # Extra RFCs -Extra RFC's implemented by mluau/luau that are not in the upstream luau-lang/luau repository. +Extra RFCs implemented by Luwu that are not in the upstream luau-lang/luau repository. -All extra RFCs should come with FFlags as well as a section in [MAINTAINERS.md](/MAINTAINERS.md) on who maintains/owns said extra RFC. +All extra RFCs should come with FFlags as well as a section in [MAINTAINERS.md](/MAINTAINERS.md) identifying who maintains and owns the RFC. -Before making a PR, please add and discuss your feature in the `#features` channel in [hina & ferris discord server](https://discord.gg/3MJ37CFNWh) +Before making a PR, please discuss your feature in the `#features` channel in the [Luwu Discord server](https://discord.gg/3MJ37CFNWh). These RFCs should always come with both an RFC and a proposed implementation. If the feature has been proposed but doesn't have an implementation, we cannot add it in until it has an implementation. You can mark as draft until you have an implementation ready. diff --git a/rfcx/api-luau-managed-refs.md b/rfcx/api-luau-managed-refs.md deleted file mode 100644 index 1b5998ae..00000000 --- a/rfcx/api-luau-managed-refs.md +++ /dev/null @@ -1,23 +0,0 @@ -# RFC: Faster Luau-managed references - -## Summary - -Add new `lua_refpool`, `lua_unrefpool` and `lua_getref` APIs to use a internal reference pool instead of the Luau registry (which is slow compared to thread stack / internal reference pool). This enables for embedders to drop hacks like thread stack etc. in favor of a native fast(er) reference API builtin to Luau and is one step towards improving the C API. The existing `lua_ref`, `lua_unref` and `lua_getref` are kept for backwards compatibility purposes. - -## Motivation - -Luau already has `lua_ref`, `lua_unref` and `lua_getref` as existing C APIs that merely work with the Luau registry (honestly should be `luaL_*` at that point?). Unfortunately, this may have performance drawbacks in certain degenerate table cases (table holes, interactions w/ the length operator for tables actually being boundary operator in Luau, performance etc.) leading to embedders like mluau choosing to instead hijack threads (or in some cases, handle multiple thread stacks) for the purpose of preventing GC. - -This RFC proposes adding new Luau-specific `lua_refpool`, `lua_unrefpool` and `lua_getrefpool` to instead make use of a separate internal pool of references with all management of free lists etc. handled directly by the VM in a way that is as fast if not faster than hacks like abusing thread stacks. Embedders like `mluau` can then drop their internal hacks like auxiliary thread stacks etc. and just use `lua_refpool`, `lua_unrefpool` and `lua_getrefpool` directly without any fears of performance loss. Additionally, the ref pool is fully isolated from the registry making it easier for embedders like `mluau` to provide a safe registry API or even directly expose the registry as a normal table. - -## Design - -`lua_getrefpool` becomes an actual function instead of a macro. A reference pool is added consisting of an array of TValues and a free list (similar to what `mluau` rust bindings does in Rust but with the extra indirection of managing a thread stack that would be fully avoidable if implemented directly in the VM). - -## Drawbacks - -Increased implementation complexity - -## Alternatives - -- Do nothing. Threads can already be abused for fast Luau-managed references anyways \ No newline at end of file diff --git a/rfcx/api-luwu-managed-refs.md b/rfcx/api-luwu-managed-refs.md new file mode 100644 index 00000000..05276b86 --- /dev/null +++ b/rfcx/api-luwu-managed-refs.md @@ -0,0 +1,23 @@ +# RFC: Faster Luwu-managed references + +## Summary + +Add new `lua_refpool`, `lua_unrefpool` and `lua_getrefpool` APIs to use an internal reference pool instead of the Luwu registry (which is slow compared to a thread stack or internal reference pool). This allows embedders to drop hacks like thread stacks in favor of a faster native reference API built into Luwu and is one step toward improving the C API. The existing `lua_ref`, `lua_unref` and `lua_getref` APIs are kept for backwards compatibility. + +## Motivation + +Luwu already has `lua_ref`, `lua_unref` and `lua_getref` as existing C APIs that merely work with the Luwu registry (honestly should be `luaL_*` at that point?). Unfortunately, this may have performance drawbacks in certain degenerate table cases (table holes, interactions w/ the length operator for tables actually being a boundary operator in Luwu, performance etc.), leading embedders like mluau to instead hijack threads (or, in some cases, handle multiple thread stacks) to prevent GC. + +This RFC proposes adding the Luwu-specific `lua_refpool`, `lua_unrefpool` and `lua_getrefpool` APIs backed by a separate internal reference pool, with free-list management handled directly by the VM. This should be at least as fast as hacks like abusing thread stacks. Embedders like `mluau` can then drop auxiliary thread stacks and use `lua_refpool`, `lua_unrefpool` and `lua_getrefpool` directly without sacrificing performance. The reference pool is also fully isolated from the registry, making it easier for embedders like `mluau` to provide a safe registry API or expose the registry directly as a normal table. + +## Design + +`lua_getrefpool` becomes an actual function instead of a macro. A reference pool is added consisting of an array of TValues and a free list (similar to what the `mluau` Rust bindings do, but without the extra indirection of managing a thread stack). + +## Drawbacks + +Increased implementation complexity + +## Alternatives + +- Do nothing. Threads can already be abused for fast Luwu-managed references. diff --git a/rfcx/external-buffers.md b/rfcx/external-buffers.md index 9ba8af8b..07ba0f1f 100644 --- a/rfcx/external-buffers.md +++ b/rfcx/external-buffers.md @@ -4,14 +4,14 @@ Status: Implemented ## Summary -Add support for external buffers to the Luau VM, allowing buffers to wrap existing host-managed memory allocations. Introduce a new C API for creating these buffers and a `buffer.isfrozen` standard library function to query their mutability. +Add support for external buffers to the Luwu VM, allowing buffers to wrap existing host-managed memory allocations. Introduce a new C API for creating these buffers and a `buffer.isfrozen` standard library function to query their mutability. ## Motivation -Luau's `buffer` type provides a way to represent fixed-size, mutable byte arrays. However, memory for standard buffers is always allocated and managed by the Luau VM itself. In many embedding scenarios (such as custom Luau runtimes), it is necessary to expose pre-existing chunks of memory (e.g., database files, images, file contents) to Luau scripts without the overhead of copying the data into a new Luau-allocated buffer. +Luwu's `buffer` type provides a way to represent fixed-size, mutable byte arrays. However, memory for standard buffers is always allocated and managed by the Luwu VM itself. In many embedding scenarios (such as custom Luwu runtimes), it is necessary to expose pre-existing chunks of memory (e.g., database files, images, file contents) to Luwu scripts without the overhead of copying the data into a new Luwu-allocated buffer. -By introducing external buffers, we allow embeddings to wrap existing memory allocations without copying, restrict mutation from scripts if necessary, and allow the Luau garbage collector to accurately track the memory footprint of externally allocated data. +By introducing external buffers, we allow embeddings to wrap existing memory allocations without copying, restrict mutation from scripts if necessary, and allow the Luwu garbage collector to accurately track the memory footprint of externally allocated data. ### Immutability @@ -21,7 +21,7 @@ Host applications often require strict immutability guarantees for shared memory ### C API Additions -The Luau C API is expanded with the following functions and types: +The Luwu C API is expanded with the following functions and types: #define LUA_BLUAU 0 #define LUA_BHOST_IMMUTABLE 1 @@ -45,7 +45,7 @@ The Luau C API is expanded with the following functions and types: * `mode` **must** be `LUA_BHOST_MUTABLE` or `LUA_BHOST_IMMUTABLE`. * Standard buffers allocated via `lua_newbuffer` implicitly use `LUA_BLUAU` as their mode. `LUA_BLUAU` cannot be passed to `lua_newexternalbuffer`. * `lua_getbuffermode` returns the mode of the buffer at the given index. -* `lua_getbufferuserdata` returns the opaque `userdata` pointer associated with the buffer, or `NULL` if the buffer is a standard Luau buffer. This allows host applications to retrieve their underlying resource structures from buffer objects passed back into C/C++ from Lua, enabling operations like downcasting a buffer back to the original host resource for native manipulation. +* `lua_getbufferuserdata` returns the opaque `userdata` pointer associated with the buffer, or `NULL` if the buffer is a standard Luwu buffer. This allows host applications to retrieve their underlying resource structures from buffer objects passed back into C/C++ from Lua, enabling operations like downcasting a buffer back to the original host resource for native manipulation. ### Lua Standard Library Additions @@ -60,5 +60,5 @@ This function returns `true` if the buffer is an external buffer created with th ## Alternatives -* **Copying:** Continue to require all host data to be copied into standard Luau buffers. This is safe but incurs unacceptable performance and memory overhead for large or frequently accessed datasets. +* **Copying:** Continue to require all host data to be copied into standard Luwu buffers. This is safe but incurs unacceptable performance and memory overhead for large or frequently accessed datasets. * **Userdata:** Expose host data through a `userdata`. This lacks integration with the standard `buffer` library (e.g. `buffer.read*32` fast-paths) and `bit32` operations, and suffers from poor performance as well as a lack of proper GC memory footprint tracking. diff --git a/rfcx/external-strings.md b/rfcx/external-strings.md index 6e83d809..c82d451e 100644 --- a/rfcx/external-strings.md +++ b/rfcx/external-strings.md @@ -2,13 +2,13 @@ ## Summary -Add support for externally managed/allocated strings to the Luau VM, allowing embedders to create zero-copy Luau strings that fully participate in all existing Luau features (like interning etc.) and behave identically to normal strings to the user. +Add support for externally managed/allocated strings to the Luwu VM, allowing embedders to create zero-copy Luwu strings that fully participate in all existing Luwu features (like interning etc.) and behave identically to normal strings to the user. ## Motivation -Luau's `string` type represents immutable byte sequences. Currently, creating a string in Luau requires copying the bytes from the host application into a VM-managed allocation. In embedding scenarios, it is common for the host to already possess large strings (such as errors w/ stack traces, data from a JSON file etc.). +Luwu's `string` type represents immutable byte sequences. Currently, creating a string in Luwu requires copying the bytes from the host application into a VM-managed allocation. In embedding scenarios, it is common for the host to already possess large strings (such as errors w/ stack traces, data from a JSON file etc.). -While external buffers do exist in Luau now, buffers cannot be manipulated by the `string` library (and other string-related operations/infrastructure) nor can they easily be used as table keys etc. Furthermore, it is expected/idiomatic for certain things in Luau to be a `string` and not a `buffer` (error tracebacks, strings in a json etc.). +While external buffers do exist in Luwu now, buffers cannot be manipulated by the `string` library (and other string-related operations/infrastructure) nor can they easily be used as table keys etc. Furthermore, it is expected/idiomatic for certain things in Luwu to be a `string` and not a `buffer` (error tracebacks, strings in a json etc.). External strings (which also have existing precedence in Lua 5.5) allows embedders to wrap these existing string allocations without copying while maintaining full access to existing string infrastructure (`string` library, tables w/ string keys etc.) @@ -16,7 +16,7 @@ External strings (which also have existing precedence in Lua 5.5) allows embedde ### C API Additions -The Luau C API is expanded with the following functions and types (similar to external buffers except w/o the mode flag as Luau strings are *always* immutable): +The Luwu C API is expanded with the following functions and types (similar to external buffers except w/o the mode flag as Luwu strings are *always* immutable): typedef void (*lua_StringFree)(lua_State* L, const char* data, size_t sz, void* userdata); @@ -39,13 +39,13 @@ The Luau C API is expanded with the following functions and types (similar to ex ### Interning & Deduplication Semantics -Unlike buffers, Luau strings are always interned (deduplicated) in a global string table so that equality comparisons can be performed via fast pointer equality. Additionally, short strings may be assigned "atoms" for fast property lookups. External strings fully participate in this interning and atom process. +Unlike buffers, Luwu strings are always interned (deduplicated) in a global string table so that equality comparisons can be performed via fast pointer equality. Additionally, short strings may be assigned "atoms" for fast property lookups. External strings fully participate in this interning and atom process. Because of interning and atoms, garbage collection (and `free_cb`) may not happen when you expect it: - If a matching string is already in the string table when you create an external string, your new allocation is deduplicated and the `free_cb` will be called prior to returning from `lua_pushexternalstring`. -- Also, even if your Luau code loses all references to the external string, the string might be kept alive by the VM internals (as an atom etc.) for longer than anticipated, delaying the `free_cb`. +- Also, even if your Luwu code loses all references to the external string, the string might be kept alive by the VM internals (as an atom etc.) for longer than anticipated, delaying the `free_cb`. When `lua_pushexternalstring` is called: @@ -55,11 +55,11 @@ When `lua_pushexternalstring` is called: 3. **Crucially**, if a duplicate is found, the provided `free_cb` is invoked (before `lua_pushexternalstring` returns) on the new external data, as the new allocation is not needed and the previous string is used instead (whether that be external or not). -From the perspective of Luau code, external strings are completely indistinguishable from normal strings. They can be concatenated, used as table keys, and queried with `string.sub` identically. +From the perspective of Luwu code, external strings are completely indistinguishable from normal strings. They can be concatenated, used as table keys, and queried with `string.sub` identically. ### Immutability and Undefined Behavior -Luau strings are strictly immutable. When an external string wraps host memory, the host **must** guarantee that the underlying bytes are never modified for the lifetime of the string object. +Luwu strings are strictly immutable. When an external string wraps host memory, the host **must** guarantee that the underlying bytes are never modified for the lifetime of the string object. Because strings are interned and hashed, modifying the underlying bytes of an active external string violates VM invariants. Doing so will result in **Undefined Behavior (UB)**. If you need mutable shared memory, use External Buffers instead. diff --git a/rfcx/fat-c-closures.md b/rfcx/fat-c-closures.md index 9fdc9c30..ac2b9164 100644 --- a/rfcx/fat-c-closures.md +++ b/rfcx/fat-c-closures.md @@ -3,17 +3,17 @@ FFlag: LuauFatCClosure ## Summary -Add a new fat c closure feature to Luau to reduce the overhead of C->Luau boundary in mluau +Add a new fat C closure feature to Luwu to reduce the overhead of the C-to-Luwu boundary in mluau. ## Motivation -Embedders like `mluau` currently need to use userdata (w/ a metatable etc.) and upvalues for every stateful closures. This has the downside of making C functions in luau a fair bit slower, increases GC pressure as the GC has to both handle the closure itself and the userdata allocation and less ergonomic for developers (involving needing upvalues etc.). `mluau` has a ton of infrastructure here regarding internal userdata with dtors which could be dropped while also increasing overall performance in general. +Embedders like `mluau` currently need to use userdata (w/ a metatable etc.) and upvalues for every stateful closure. This has the downside of making C functions in Luwu a fair bit slower, increasing GC pressure because the GC has to handle both the closure and the userdata allocation, and making the API less ergonomic for developers. `mluau` has a significant amount of infrastructure for internal userdata with destructors that could be dropped while improving overall performance. This RFC as such proposes the addition of 'fat' C closures (or C Closures with Data). A stateful closure that would otherwise require a full userdata + 1 upvalue + closure can now be directly done as a single closure reducing GC pressure (1 gc object vs 2) and improving memory layout + cacheability. ## Design -A new C API will be added to Luau for pushing c closures with data and getting out the data from the running closure: +A new C API will be added to Luwu for pushing C closures with data and retrieving the data from the running closure: ```c typedef void (*lua_ClosureWithDataFree)(lua_State* L, void* data, size_t sz); @@ -36,7 +36,7 @@ LUA_API void* lua_getcclosuredata(lua_State *L); Like userdata, the data stored in a closure with data (herein called 'fat' C closures) are fully opaque and will not be scanned or traced by GC (embedders will need to make sure any references are stored in either the registry or a thread stack etc). Additionally, the data will be inline to the closure hence enabling for better memory layout/caching. -Also like userdata, when the Luau state is closed, all fat c closure dtors will be called. Note that the order of GC is undefined and should not be relied upon. +As with userdata, when the Luwu state is closed, all fat C closure destructors will be called. Note that the order of GC is undefined and should not be relied upon. ## Drawbacks @@ -44,4 +44,4 @@ Implementation complexity. While this shouldn't have any performance loss for ex ## Alternatives -- Do nothing. Userdata (with dtors) and upvalues can already be used to implement this feature, just at the cost of more memory allocations and increased GC overhead. \ No newline at end of file +- Do nothing. Userdata (with dtors) and upvalues can already be used to implement this feature, just at the cost of more memory allocations and increased GC overhead. diff --git a/rfcx/function-default-arguments.md b/rfcx/function-default-arguments.md index 1b3bc498..93a7b28f 100644 --- a/rfcx/function-default-arguments.md +++ b/rfcx/function-default-arguments.md @@ -8,7 +8,7 @@ Add default values to arguments in function definitions, used when a parameter i ## Motivation -Frequently when writing code, having a default value for an unspecified argument is desired. This can be found in a range of languages, such as C++ and Python. Luau has no first-party support for this, instead filling omitted arguments as `nil` allowing programmers to begin their functions with a series of statements such as: +Frequently when writing code, having a default value for an unspecified argument is desired. This can be found in a range of languages, such as C++ and Python. Upstream Luau has no first-party support for this, instead filling omitted arguments as `nil` and requiring programmers to begin their functions with a series of statements such as: ```lua arg = arg or default @@ -24,7 +24,7 @@ arg = if arg == nil then default else arg While effective this produces a degree of noise at the start of functions. Notably also the `or` short-circuit approach will coalesce all falsey values to the default value, rather than just `nil` values. -The luau type system also does not currently narrow these types correctly. For example, +The Luwu type system also does not currently narrow these types correctly. For example, ```lua function demo_type(arg: number?) if arg == nil then arg = 0 end @@ -34,26 +34,25 @@ end ``` will result in `x` having an inferred type of `number?` and the function having a return type of `number?`. Resolving this involves creating a new variable name for the parameter post-defaulting rather than shadowing the name. This RFC explicitly hides the optional nature of arguments from the function body. -Further, this defaulting behavior is hidden from tooling that may want to inspect function signatures, such as tooltips in IDEs. A handful of examples from the Roblox standard library that could benefit have been included here: +Further, this defaulting behavior is hidden from tooling that may want to inspect function signatures, such as tooltips in IDEs. A handful of API examples that could benefit are included here: ```lua -function color3.new(x = 0, y = 0, z = 0) +function Color.new(red = 0, green = 0, blue = 0) function Vector3.new(x = 0, y = 0, z = 0) -function CFrame.fromEulerAngles(rx: number, ry: number, rz: number, order = Enum.RotationOrder.XYZ) -function DataStoreService:GetDataStore(name: string, scope = "global", options: DataStoreOptions?) -function DataStoreService:ListDataStoresAsync(prefix = "", pageSize = 0, cursor = "") +function Matrix.fromEulerAngles(rx: number, ry: number, rz: number, order = RotationOrder.XYZ) +function Store:Get(name: string, scope = "global", options: StoreOptions?) +function Store:List(prefix = "", pageSize = 100, cursor = "") ``` -A slightly more complicated Roblox example could call API functions in the default value, for example: +A slightly more complicated example could call API functions in the default value: ```lua -local Players = game:GetService("Players") -function give_players_item(item, players = Players:GetPlayers()) +function notify_users(message, users = UserService:GetUsers()) ``` ## Design -This proposal at its core suggests the following modification to the luau grammar: +This proposal at its core suggests the following modification to the Luwu grammar: ```diff - parlist = bindinglist [',' '...' [':' GenericTypePack | Type]] @@ -194,7 +193,7 @@ end ### Language implementation Within the AST, it would likely be simpler to add a new `AstArray argsDefaults` to `AstExprFunction` alongside `args`, rather than modify `args` to be an `std::pair` due to the existing widespread usage of `args`. -Rather than implement this as a feature of the `CALL` instruction within Luau's VM it is instead suggested by this RFC to implement this as part of the compiler. This both increases compatibility (as the VM remains unchanged) and makes it easier to allow *any* expression to be used. +Rather than implement this as a feature of the `CALL` instruction within Luwu's VM, this RFC proposes implementing it as part of the compiler. This both increases compatibility (as the VM remains unchanged) and makes it easier to allow *any* expression to be used. Each defaulted argument can be implemented using a single inverted `JUMPXEQKNIL` instruction followed by a `compileExpr` call. This costs no additional registers beyond what would be already necessary for evaluation of the expression. diff --git a/rfcx/none.md b/rfcx/none.md index fc73e57f..22044711 100644 --- a/rfcx/none.md +++ b/rfcx/none.md @@ -6,11 +6,11 @@ FFlag: `LuauNonePrimitive` ## Summary -Introduce `none` as a new first-class primitive value and built-in global in Luau, representing an intentional "no value" sentinel distinct from `nil`. Unlike `nil`, which denotes the absence of a value or an unassigned state, `none` is an explicit primitive of type `"none"`. It is falsy in boolean evaluation contexts, compares equal only to itself (`none == none` is `true` while `nil ~= none`), and does not delete table entries or create array holes when stored as a table value (`t[k] = none`). +Introduce `none` as a new first-class primitive value and built-in global in Luwu, representing an intentional "no value" sentinel distinct from `nil`. Unlike `nil`, which denotes the absence of a value or an unassigned state, `none` is an explicit primitive of type `"none"`. It is falsy in boolean evaluation contexts, compares equal only to itself (`none == none` is `true` while `nil ~= none`), and does not delete table entries or create array holes when stored as a table value (`t[k] = none`). ## Motivation -In Luau and Lua, `nil` serves two conflicting roles: indicating the absence of a value (such as an uninitialized variable, omitted function argument, or non-existent table key) and acting as an intentional empty sentinel in data structures and APIs. Because assigning `t[k] = nil` removes key `k` from table `t`, developers cannot store an explicit empty sentinel in a table without resorting to workaround objects (such as `local NONE = {}` or unique userdata sentinels). +In Luwu and Lua, `nil` serves two conflicting roles: indicating the absence of a value (such as an uninitialized variable, omitted function argument, or non-existent table key) and acting as an intentional empty sentinel in data structures and APIs. Because assigning `t[k] = nil` removes key `k` from table `t`, developers cannot store an explicit empty sentinel in a table without resorting to workaround objects (such as `local NONE = {}` or unique userdata sentinels). In standard Luau, assigning `nil` to an index within a sequential array creates a "hole" (e.g., `{ 1, nil, 3 }`). The `#` length operator on sparse tables is defined to return an arbitrary array boundary, making `#t` and sequential iteration via `ipairs` unpredictable when representing lists with missing or nullable entries. With the `none` primitive, array elements can be explicitly set to `none` (`local list = { 1, none, 3 }`). Because `none` is a stored value and does not leave holes, `#list` reliably evaluates to `3`, and sequential iteration visits every index without breaking sequence invariants. @@ -32,7 +32,7 @@ When `LuauNonePrimitive` is enabled, `none` is exposed as a built-in global valu ### Runtime Semantics and Comparison 1. **Falsiness:** - In all boolean evaluation contexts (`if`, `elseif`, `while`, `until`, and logical operators `and`, `or`, `not`), `none` evaluates as **falsy**. The set of falsy values in Luau is exactly `false`, `nil`, and `none`. All other values are truthy. + In all boolean evaluation contexts (`if`, `elseif`, `while`, `until`, and logical operators `and`, `or`, `not`), `none` evaluates as **falsy**. The set of falsy values in Luwu is exactly `false`, `nil`, and `none`. All other values are truthy. ```lua assert(not none == true) assert((none or "fallback") == "fallback") diff --git a/rfcx/thread-statechange-hook.md b/rfcx/thread-statechange-hook.md index 14a989c5..746e3d37 100644 --- a/rfcx/thread-statechange-hook.md +++ b/rfcx/thread-statechange-hook.md @@ -8,15 +8,15 @@ Add a new C-level callback to `lua_Callbacks` called `userthreadstatechange` to ## Motivation -Luau is commonly paired with custom async task schedulers (like `mluau/scheduler`, other async impls). To track when a thread yields, finishes or errors, schedulers currently patch the global `coroutine.resume` function with a wrapper that intercepts the call, records the result in their scheduler, and forwards the return values. +Luwu is commonly paired with custom async task schedulers (like `mluau/scheduler`, other async impls). To track when a thread yields, finishes or errors, schedulers currently patch the global `coroutine.resume` function with a wrapper that intercepts the call, records the result in their scheduler, and forwards the return values. -Ideally, scheduling would be a first class part of Luau but this is a future goal and is orthogonal to this RFC. +Ideally, scheduling would be a first class part of Luwu but this is a future goal and is orthogonal to this RFC. This approach has several flaws: - Every scheduler needs to manually patch `coroutine` library by hand to correctly track coroutine.resume thread states - Threads resumed directly via the C API (`lua_resume`) will not trigger the scheduler's patched `coroutine.resume` func making the scheduler entirely blind to these manual thread resumes. -- Crossing the Luau-C/Rust boundary to intercept `coroutine.resume` calls incurs extra FFI overhead. +- Crossing the Luwu-C/Rust boundary to intercept `coroutine.resume` calls incurs extra FFI overhead. By providing a native VM hook, schedulers can deterministically track thread state transitions with negligible performance penalty when unused.