feat(rust): establish Rust graph computing modernization framework (#355)

.github/workflows/rust-ci.yml

@@ -0,0 +1,78 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+name: "Rust CI"
+
+on:
+  push:
+    branches:
+      - master
+      - 'release-*'
+    paths:
+      - computer-rust/**
+      - .github/workflows/rust-ci.yml
+  pull_request:
+    paths:
+      - computer-rust/**
+      - .github/workflows/rust-ci.yml
+
+defaults:
+  run:
+    working-directory: computer-rust
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  rust-check:
+    name: Rust Code Quality & Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+
+      - name: Cache Cargo dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            computer-rust/target/
+          key: ${{ runner.os }}-cargo-${{ hashFiles('computer-rust/Cargo.toml') }}
+          restore-keys: ${{ runner.os }}-cargo-
+
+      - name: Check code formatting
+        run: cargo fmt --check
+
+      - name: Run clippy lints
+        run: cargo clippy --all-targets -- -D warnings
+
+      - name: Run tests
+        run: cargo test --all-targets --verbose
+
+      - name: Build release library
+        run: cargo build --release
+
+      - name: Build benchmarks
+        run: cargo bench --no-run

.licenserc.yaml

@@ -73,6 +73,7 @@ header: # `header` section is configurations for source codes license header.
     - '**/target/*'
     - '**/go.mod'
     - '**/go.sum'
+    - '**/Cargo.lock'
   comment: on-failure # on what condition license-eye will comment on the pull request, `on-failure`, `always`, `never`.
 
   # license-location-threshold specifies the index threshold where the license header can be located,

computer-rust/Cargo.toml

@@ -0,0 +1,43 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+[package]
+name = "hugegraph-computer-rust"
+version = "1.5.0"
+edition = "2021"
+authors = ["Apache HugeGraph Authors <dev@hugegraph.apache.org>"]
+license = "Apache-2.0"
+description = "High-performance Rust graph computing kernels for HugeGraph Computer and Vermeer"
+repository = "https://github.com/apache/hugegraph-computer"
+
+[lib]
+name = "hugegraph_computer_rust"
+crate-type = ["cdylib", "staticlib", "rlib"]
+
+[dependencies]
+libc = "0.2"
+
+[dev-dependencies]
+criterion = "0.5"
+
+[[bench]]
+name = "kernel_bench"
+harness = false
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1
+panic = "abort"

computer-rust/benches/kernel_bench.rs

@@ -0,0 +1,31 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+use criterion::{criterion_group, criterion_main, Criterion};
+use hugegraph_computer_rust::fixtures::dataset::GraphFixture;
+use hugegraph_computer_rust::kernel::pagerank::PageRankKernel;
+
+fn bench_pagerank(c: &mut Criterion) {
+    let fixture = GraphFixture::synthetic_powerlaw(1000, 10);
+    let csr = fixture.to_csr();
+    let kernel = PageRankKernel::new(0.85, 20, 1e-4);
+
+    c.bench_function("pagerank_1k_vertices", |b| b.iter(|| kernel.compute(&csr)));
+}
+
+criterion_group!(benches, bench_pagerank);
+criterion_main!(benches);

computer-rust/include/computer_rust_c_api.h

@@ -0,0 +1,83 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef HUGEGRAPH_COMPUTER_RUST_C_API_H
+#define HUGEGRAPH_COMPUTER_RUST_C_API_H
+
+#include <stddef.h>
+#include <stdint.h>
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct GraphHandle GraphHandle;
+
+/**
+ * Creates a new GraphHandle instance with the specified number of vertices.
+ */
+GraphHandle* computer_graph_create(uint32_t num_vertices);
+
+/**
+ * Adds a directed edge from src to dst with a weight.
+ * @return 0 on success.
+ * @return -1 if handle is NULL, endpoints src/dst are >= num_vertices, or weight < 0.0 or non-finite.
+ * @return -2 if graph has already been finalized.
+ */
+int32_t computer_graph_add_edge(GraphHandle* handle, uint32_t src, uint32_t dst, double weight);
+
+/**
+ * Finalizes graph topology into Compressed Sparse Row (CSR) structure.
+ * @return 0 on success, -1 if handle is NULL.
+ */
+int32_t computer_graph_finalize(GraphHandle* handle);
+
+/**
+ * Computes PageRank on the CSR graph structure.
+ * Results array must be allocated by caller with capacity >= num_vertices.
+ * @return 0 on success.
+ * @return -1 if handle or out_scores is NULL.
+ * @return -2 if graph is not finalized (CSR missing).
+ * @return -3 if out_capacity < num_vertices.
+ * @return -4 if damping_factor or tolerance is invalid (non-finite, negative, or damping > 1.0).
+ */
+int32_t computer_graph_compute_pagerank(
+    const GraphHandle* handle,
+    double damping_factor,
+    uint32_t max_iterations,
+    double tolerance,
+    double* out_scores,
+    uint32_t out_capacity
+);
+
+/**
+ * Frees the GraphHandle resources.
+ */
+void computer_graph_free(GraphHandle* handle);
+
+/**
+ * Returns the version string of the Rust kernel library.
+ * Pointer references process-lifetime static storage and remains valid across threads.
+ */
+const char* computer_kernel_version(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* HUGEGRAPH_COMPUTER_RUST_C_API_H */