Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1,284 changes: 890 additions & 394 deletions Cargo.lock

Large diffs are not rendered by default.

8 changes: 5 additions & 3 deletions Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
[workspace]
resolver = "3"
members = [
"examples/async-sqlite",
"examples/cpu-count",
Expand All @@ -7,8 +8,9 @@ members = [
"examples/tokio-fetch",
]

[workspace.dependencies.neon]
version = "1.2.0-alpha.0"
features = ["tokio"]

[profile.release]
lto = true

[patch.crates-io]
neon = { git = "https://github.com/neon-bindings/neon.git" }
4 changes: 0 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,7 @@

Examples and common patterns for [Neon][neon].

All examples are for [`napi-backend`][napi-migration]. For examples using `legacy-backend` see the [`legacy`][legacy] branch.

[neon]: https://github.com/neon-bindings/neon
[napi-migration]: https://github.com/neon-bindings/neon/blob/main/MIGRATION_GUIDE.md#n-api-migration-guide
[legacy]: https://github.com/neon-bindings/examples/tree/legacy

## Table of Contents

Expand Down
6 changes: 3 additions & 3 deletions examples/async-sqlite/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,12 @@ name = "async-sqlite"
version = "0.1.0"
description = "Neon Async SQLite"
license = "MIT"
edition = "2018"
edition = "2024"
exclude = ["index.node"]

[lib]
crate-type = ["cdylib"]

[dependencies]
neon = "1"
rusqlite = "0.25"
neon.workspace = true
rusqlite = "0.37.0"
15 changes: 4 additions & 11 deletions examples/async-sqlite/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ The Async SQLite example implements a simple database in Rust with a JavaScript
## Usage

```js
const Database = require(".");
const { Database } = require(".");

(async () => {
const db = new Database();
Expand All @@ -31,25 +31,18 @@ Since SQLite is naturally single threaded, our application does not benefit from

Once the database thread is spawned, the JavaScript main thread needs a way to communicate with it. A [multi-producer, single-consumer (mpsc)][mpsc] channel is created. The receiving end is owned by the database thread and the sender is held by JavaScript.

#### `JsBox`
#### `#[neon::export(class)]`

Rust data cannot be directly held by JavaScript. The [`JsBox`][jsbox] provides a mechanism for allowing JavaScript to hold a reference to Rust data and later access it again from Rust.
The Rust sender side of the channel is held in a JavaScript [class][class]. It can be referenced later in methods.

#### Rust and Neon Channels

The mpsc channel provides a way for the JavaScript main thread to communicate with the database thread, but it is one-way. In order to complete the callback, the database thread must be able to communicate with the JavaScript main thread. [`neon::event::Channel`][channel] provides a channel for sending these events back.

#### `Root`

The last issue to solve is sending a reference to the JavaScript callback to the database thread and back again before finally calling it. [Handles][handle] to JavaScript values are not `Send`; they cannot escape the scope that created them. The reason they cannot be passed to other threads is because when control is returned back to the JavaScript engine, the garbage collector may determine they are no longer used and free the value.

A [`Root`][root] is a special handle to a JavaScript value that prevents the value from being freed as long as the `Root` has not been dropped. By placing the callback in a `Root`, it can be safely sent across threads and finally accessed and called when back on the JavaScript main thread.

### JavaScript

[thread]: https://doc.rust-lang.org/std/thread/
[mpsc]: https://doc.rust-lang.org/std/sync/mpsc/index.html
[jsbox]: https://docs.rs/neon/latest/neon/types/struct.JsBox.html
[class]: https://docs.rs/neon/latest/neon/attr.class.html
[channel]: https://docs.rs/neon/latest/neon/event/struct.Channel.html
[handle]: https://docs.rs/neon/latest/neon/handle/struct.Handle.html
[root]: https://docs.rs/neon/latest/neon/handle/struct.Root.html
29 changes: 0 additions & 29 deletions examples/async-sqlite/index.js

This file was deleted.

2 changes: 1 addition & 1 deletion examples/async-sqlite/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "async-sqlite",
"version": "0.1.0",
"description": "Neon Async SQLite",
"main": "index.js",
"main": "index.node",
"scripts": {
"build": "cargo-cp-artifact -nc index.node -- cargo build --message-format=json-render-diagnostics",
"install": "npm run build",
Expand Down
Loading
Loading