{"id":26171892,"url":"https://github.com/shikokuchuo/sakura","last_synced_at":"2025-04-14T20:21:21.141Z","repository":{"id":270746675,"uuid":"911338415","full_name":"shikokuchuo/sakura","owner":"shikokuchuo","description":"Extension to R Serialization","archived":false,"fork":false,"pushed_at":"2025-04-06T10:03:15.000Z","size":1637,"stargazers_count":16,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T11:18:49.200Z","etag":null,"topics":["marshalling","r","serialization"],"latest_commit_sha":null,"homepage":"https://shikokuchuo.net/sakura/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shikokuchuo.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-02T19:29:23.000Z","updated_at":"2025-04-06T10:00:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"646549fd-343e-4aef-931a-449e5cfb9b5a","html_url":"https://github.com/shikokuchuo/sakura","commit_stats":null,"previous_names":["shikokuchuo/sakura"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shikokuchuo%2Fsakura","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shikokuchuo%2Fsakura/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shikokuchuo%2Fsakura/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shikokuchuo%2Fsakura/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shikokuchuo","download_url":"https://codeload.github.com/shikokuchuo/sakura/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248952344,"owners_count":21188427,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["marshalling","r","serialization"],"created_at":"2025-03-11T19:52:14.823Z","updated_at":"2025-04-14T20:21:21.115Z","avatar_url":"https://github.com/shikokuchuo.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n# sakura\n\n\u003c!-- badges: start --\u003e\n[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)\n[![CRAN status](https://www.r-pkg.org/badges/version/sakura)](https://CRAN.R-project.org/package=sakura)\n[![R-CMD-check](https://github.com/shikokuchuo/sakura/workflows/R-CMD-check/badge.svg)](https://github.com/shikokuchuo/sakura/actions)\n[![Codecov test coverage](https://codecov.io/gh/shikokuchuo/sakura/graph/badge.svg)](https://app.codecov.io/gh/shikokuchuo/sakura)\n\u003c!-- badges: end --\u003e\n\n```\n  ________  \n /\\ sa    \\\n/  \\  ku   \\\n\\  /    ra /\n \\/_______/\n```\n\n### Extension to R Serialization\n\nExtends the functionality of R serialization by augmenting the built-in reference hook system. This enhanced implementation allows an integrated single-pass operation that combines R serialization with third-party serialization methods.\n\nFacilitates the serialization of even complex R objects, which contain non-system reference objects, such as those accessed via external pointers, to enable their use in parallel and distributed computing.\n\nThis package was a request from a meeting of the [R Consortium](https://r-consortium.org/) [Marshalling and Serialization Working Group](https://github.com/RConsortium/marshalling-wg/) held at useR!2024 in Salzburg, Austria. It is designed to eventually provide a common framework for marshalling in R.\n\nIt extracts the functionality embedded within the [mirai](https://github.com/shikokuchuo/mirai) async framework for use in other contexts.\n\n### Installation\n\nInstall the current release from CRAN:\n\n```{r cran, eval=FALSE}\ninstall.packages(\"sakura\")\n```\n\nOr the development version using:\n\n```{r devinstall, eval=FALSE}\npak::pak(\"shikokuchuo/sakura\")\n```\n\n### Overview\n\nSome R objects by their nature cannot be serialized, such as those accessed via an external pointer.\n\nUsing the [`arrow`](https://arrow.apache.org/docs/r/) package as an example:\n\n```{r arrowfail,error=TRUE}\nlibrary(arrow, warn.conflicts = FALSE)\nobj \u003c- list(as_arrow_table(iris), as_arrow_table(mtcars))\n\nunserialize(serialize(obj, NULL))\n```\nIn such cases, `sakura::serial_config()` can be used to create custom serialization configurations, specifying functions that hook into R's native serialization mechanism for reference objects ('refhooks').\n\n```{r arrowcfg}\ncfg \u003c- sakura::serial_config(\n  \"ArrowTabular\",\n  arrow::write_to_raw,\n  function(x) arrow::read_ipc_stream(x, as_data_frame = FALSE)\n)\n```\nThis configuration can then be supplied as the 'hook' argument for `sakura::serialize()` and `sakura::unserialize()`.\n```{r arrowpass}\nsakura::unserialize(sakura::serialize(obj, cfg), cfg)\n```\nThis time, the arrow tables are handled seamlessly.\n\nOther types of serialization function are vectorized and in this case, the configuration should be created specifying `vec = TRUE`. Using `torch` as an example:\n\n```{r torchfail, error=TRUE}\nlibrary(torch)\nx \u003c- list(torch_rand(5L), runif(5L))\n\nunserialize(serialize(x, NULL))\n```\nBase R serialization above fails, but `sakura` serialization succeeds:\n\n```{r torchpass}\ncfg \u003c- sakura::serial_config(\"torch_tensor\", torch::torch_serialize, torch::torch_load, vec = TRUE)\n\nsakura::unserialize(sakura::serialize(x, cfg), cfg)\n```\n\n### C Interface\n\nA C level interface is provided. A public header file `sakura.h` is available in `inst/include` for all packages that declare sakura in `LinkingTo`. This may be used in the following way:\n\n```c\n#include \u003csakura.h\u003e\n\nsakura_sfunc sakura_serialize;\nsakura_ufunc sakura_unserialize;\n\n// runtime initialization:\nsakura_serialize = (sakura_sfunc) R_GetCCallable(\"sakura\", \"sakura_serialize\");\nsakura_unserialize = (sakura_ufunc) R_GetCCallable(\"sakura\", \"sakura_unserialize\");\n```\n\n### Acknowledgements\n\nWe would like to thank in particular:\n\n- [R Core](https://www.r-project.org/contributors.html) for providing the interface to the R serialization mechanism.\n- [Luke Tierney](https://github.com/ltierney/) and [Mike Cheng](https://github.com/coolbutuseless) for their meticulous efforts in documenting the serialization interface.\n- [Daniel Falbel](https://github.com/dfalbel) for discussion around an efficient solution to serialization and transmission of torch tensors.\n\n--\n\nPlease note that this project is released with a [Contributor Code of Conduct](https://shikokuchuo.net/sakura/CODE_OF_CONDUCT.html). By participating in this project you agree to abide by its terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshikokuchuo%2Fsakura","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshikokuchuo%2Fsakura","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshikokuchuo%2Fsakura/lists"}