galaaz 2.1.7 → 2.1.9

data/blogs/galaaz_2_0/galaaz_2_0.tex

@@ -0,0 +1,756 @@
+% Options for packages loaded elsewhere
+\PassOptionsToPackage{unicode}{hyperref}
+\PassOptionsToPackage{hyphens}{url}
+\documentclass[
+  11pt,
+]{article}
+\usepackage{xcolor}
+\usepackage[margin=1in]{geometry}
+\usepackage{amsmath,amssymb}
+\setcounter{secnumdepth}{5}
+\usepackage{iftex}
+\ifPDFTeX
+  \usepackage[T1]{fontenc}
+  \usepackage[utf8]{inputenc}
+  \usepackage{textcomp} % provide euro and other symbols
+\else % if luatex or xetex
+  \usepackage{unicode-math} % this also loads fontspec
+  \defaultfontfeatures{Scale=MatchLowercase}
+  \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
+\fi
+\usepackage{lmodern}
+\ifPDFTeX\else
+  % xetex/luatex font selection
+\fi
+% Use upquote if available, for straight quotes in verbatim environments
+\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
+\IfFileExists{microtype.sty}{% use microtype if available
+  \usepackage[]{microtype}
+  \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
+}{}
+\makeatletter
+\@ifundefined{KOMAClassName}{% if non-KOMA class
+  \IfFileExists{parskip.sty}{%
+    \usepackage{parskip}
+  }{% else
+    \setlength{\parindent}{0pt}
+    \setlength{\parskip}{6pt plus 2pt minus 1pt}}
+}{% if KOMA class
+  \KOMAoptions{parskip=half}}
+\makeatother
+\usepackage{color}
+\usepackage{fancyvrb}
+\newcommand{\VerbBar}{|}
+\newcommand{\VERB}{\Verb[commandchars=\\\{\}]}
+\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\}}
+% Add ',fontsize=\small' for more characters per line
+\usepackage{framed}
+\definecolor{shadecolor}{RGB}{248,248,248}
+\newenvironment{Shaded}{\begin{snugshade}}{\end{snugshade}}
+\newcommand{\AlertTok}[1]{\textcolor[rgb]{0.94,0.16,0.16}{#1}}
+\newcommand{\AnnotationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\newcommand{\AttributeTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{#1}}
+\newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
+\newcommand{\BuiltInTok}[1]{#1}
+\newcommand{\CharTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
+\newcommand{\CommentTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{#1}}}
+\newcommand{\CommentVarTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\newcommand{\ConstantTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{#1}}
+\newcommand{\ControlFlowTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
+\newcommand{\DataTypeTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{#1}}
+\newcommand{\DecValTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
+\newcommand{\DocumentationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\newcommand{\ErrorTok}[1]{\textcolor[rgb]{0.64,0.00,0.00}{\textbf{#1}}}
+\newcommand{\ExtensionTok}[1]{#1}
+\newcommand{\FloatTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
+\newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
+\newcommand{\ImportTok}[1]{#1}
+\newcommand{\InformationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
+\newcommand{\NormalTok}[1]{#1}
+\newcommand{\OperatorTok}[1]{\textcolor[rgb]{0.81,0.36,0.00}{\textbf{#1}}}
+\newcommand{\OtherTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{#1}}
+\newcommand{\PreprocessorTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{#1}}}
+\newcommand{\RegionMarkerTok}[1]{#1}
+\newcommand{\SpecialCharTok}[1]{\textcolor[rgb]{0.81,0.36,0.00}{\textbf{#1}}}
+\newcommand{\SpecialStringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
+\newcommand{\StringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
+\newcommand{\VariableTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
+\newcommand{\VerbatimStringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
+\newcommand{\WarningTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\usepackage{longtable,booktabs,array}
+\newcounter{none} % for unnumbered tables
+\usepackage{calc} % for calculating minipage widths
+% Correct order of tables after \paragraph or \subparagraph
+\usepackage{etoolbox}
+\makeatletter
+\patchcmd\longtable{\par}{\if@noskipsec\mbox{}\fi\par}{}{}
+\makeatother
+% Allow footnotes in longtable head/foot
+\IfFileExists{footnotehyper.sty}{\usepackage{footnotehyper}}{\usepackage{footnote}}
+\makesavenoteenv{longtable}
+\usepackage{graphicx}
+\makeatletter
+\newsavebox\pandoc@box
+\newcommand*\pandocbounded[1]{% scales image to fit in text height/width
+  \sbox\pandoc@box{#1}%
+  \Gscale@div\@tempa{\textheight}{\dimexpr\ht\pandoc@box+\dp\pandoc@box\relax}%
+  \Gscale@div\@tempb{\linewidth}{\wd\pandoc@box}%
+  \ifdim\@tempb\p@<\@tempa\p@\let\@tempa\@tempb\fi% select the smaller of both
+  \ifdim\@tempa\p@<\p@\scalebox{\@tempa}{\usebox\pandoc@box}%
+  \else\usebox{\pandoc@box}%
+  \fi%
+}
+% Set default figure placement to htbp
+\def\fps@figure{htbp}
+\makeatother
+\setlength{\emergencystretch}{3em} % prevent overfull lines
+\providecommand{\tightlist}{%
+  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+% usar portugues do Brasil
+% \usepackage[brazilian]{babel}
+\usepackage[utf8]{inputenc}
+
+\usepackage{geometry}
+\geometry{a4paper, top=1.05in, headheight=30pt, headsep=14pt}
+
+% needed for kableExtra
+\usepackage{longtable}
+\usepackage{multirow}
+\usepackage[table]{xcolor}
+\usepackage{wrapfig}
+\usepackage{float}
+\usepackage{colortbl}
+\usepackage{pdflscape}
+\usepackage{tabu}
+\usepackage{threeparttable}
+\usepackage[normalem]{ulem}
+
+\usepackage{bbm}
+\usepackage{booktabs}
+\usepackage{expex}
+
+\usepackage{graphicx}
+
+\usepackage{fancyhdr}
+% Header: small Galaaz mark (left); page number + section title (right),
+% matching classic LaTeX style: "4  AN EXTENSION TO THE EXAMPLE"
+% (upright page number, uppercase italic section name).
+% Logo paths cover repo blogs (../../sty/), installed ~/sty/, and local images/.
+% Blogs may delay headers with \renewcommand{\galaazheaderfrompage}{3} after this sty
+% (e.g. skip title/TOC and a logo splash page).
+\newcommand{\galaazheaderfrompage}{1}
+\newcommand{\galaazheaderlogo}{%
+  \raisebox{-0.12\height}{%
+    \IfFileExists{../../sty/galaaz-header.png}{%
+      \includegraphics[height=0.32in]{../../sty/galaaz-header.png}%
+    }{%
+      \IfFileExists{galaaz-header.png}{%
+        \includegraphics[height=0.32in]{galaaz-header.png}%
+      }{%
+        \IfFileExists{images/galaaz-header.png}{%
+          \includegraphics[height=0.32in]{images/galaaz-header.png}%
+        }{}%
+      }%
+    }%
+  }%
+}
+% Section title only in marks (no \thesection); page number is separate.
+\renewcommand{\sectionmark}[1]{\markboth{#1}{}}
+\renewcommand{\subsectionmark}[1]{}% keep the current section in the header
+\newcommand{\galaazmaybeheaderlogo}{%
+  \ifnum\value{page}<\galaazheaderfrompage\relax\else\galaazheaderlogo\fi}
+\newcommand{\galaazmayberighthead}{%
+  \ifnum\value{page}<\galaazheaderfrompage\relax
+  \else
+    \textup{\thepage}\hspace{1em}\textit{\MakeUppercase{\leftmark}}%
+  \fi
+}
+\pagestyle{fancy}
+\fancyhf{}
+\fancyhead[L]{\galaazmaybeheaderlogo}
+\fancyhead[R]{\galaazmayberighthead}
+\renewcommand{\headrulewidth}{0.3pt}
+\makeatletter
+\renewcommand{\headrule}{%
+  \ifnum\value{page}<\galaazheaderfrompage\relax
+  \else
+    \hrule\@height\headrulewidth\@width\headwidth
+    \vskip-\headrulewidth
+  \fi
+}
+\makeatother
+% First page often uses plain; same conditional header logic.
+\fancypagestyle{plain}{%
+  \fancyhf{}%
+  \fancyhead[L]{\galaazmaybeheaderlogo}%
+  \fancyhead[R]{\galaazmayberighthead}%
+  \renewcommand{\headrulewidth}{0.3pt}%
+}
+
+% make available command lastpage
+\usepackage{lastpage}
+
+% default fontsize 11pt better to add
+% fontsize on the yaml header
+% \usepackage[fontsize=11pt]{scrextend}
+
+% comandos para formatar uma tabela
+\usepackage{array}
+\newcolumntype{L}[1]{>{\raggedright\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
+\newcolumntype{C}[1]{>{\centering\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
+\newcolumntype{R}[1]{>{\raggedleft\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
+
+% necessário if we need to import other latex documents
+\usepackage{import}
+
+% Command to import an R variable to latex
+\newcommand{\RtoLatex}[2]{\newcommand{#1}{#2}}
+
+% Soft-wrap Pandoc highlighted code/output boxes (Shaded + Highlighting).
+% This runs after Pandoc's default \DefineVerbatimEnvironment{Highlighting}
+% (header includes come later in the generated .tex). Prefer manual line
+% breaks in Rmd sources; breaklines is a safety net for leftovers/output.
+% Requires TinyTeX/TeX Live package: tlmgr install fvextra
+\IfFileExists{fvextra.sty}{%
+  \usepackage{fvextra}%
+  \DefineVerbatimEnvironment{Highlighting}{Verbatim}{%
+    breaklines=true,
+    breakanywhere=true,
+    breakindent=1.5em,
+    fontsize=\small,
+    commandchars=\\\{\}%
+  }%
+}{%
+  % fancyvrb is already loaded by Pandoc; shrink code so more fits per line.
+  \DefineVerbatimEnvironment{Highlighting}{Verbatim}{%
+    fontsize=\small,
+    commandchars=\\\{\}%
+  }%
+}
+
+% 
+%\newcommand{\atraso}[1]{\color{red} \textbf {Tempo desde a Assinatura do Contrato: #1 dias}}
+% No header on title/TOC (p.1) or splash logo page (p.2);
+% logo + page number + section title from page 3 onward.
+% Load after galaaz.sty.
+\renewcommand{\galaazheaderfrompage}{3}
+\usepackage{bookmark}
+\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
+\urlstyle{same}
+\hypersetup{
+  pdftitle={Galaaz 2.0: Ruby meets real GNU R (again)},
+  pdfauthor={Rodrigo Botafogo},
+  hidelinks,
+  pdfcreator={LaTeX via pandoc}}
+
+\title{Galaaz 2.0: Ruby meets real GNU R (again)}
+\usepackage{etoolbox}
+\makeatletter
+\providecommand{\subtitle}[1]{% add subtitle to \maketitle
+  \apptocmd{\@title}{\par {\large #1 \par}}{}{}
+}
+\makeatother
+\subtitle{NewBridge, JRuby or CRuby, CRAN/Bioconductor, and Arrow-shaped
+data paths}
+\author{Rodrigo Botafogo}
+\date{2026}
+
+\begin{document}
+\maketitle
+
+{
+\setcounter{tocdepth}{2}
+\tableofcontents
+}
+\begin{center}\includegraphics[width=0.45\linewidth]{images/galaaz-lockup-stacked} \end{center}
+
+\section{Introduction}\label{introduction}
+
+Ruby is excellent for web apps, orchestration, and expressive object
+models. It has never matched \textbf{R} for statistics, Bioconductor
+pipelines, or the depth of CRAN. \textbf{Python} closed a similar gap
+with NumPy, pandas, and a huge scientific ecosystem. For Ruby, the
+practical answer is not to reimplement that world --- it is to
+\textbf{drive real R} from idiomatic Ruby.
+
+\textbf{Galaaz} is that coupling. An earlier line of work ran on
+Oracle's \textbf{GraalVM} with \textbf{TruffleRuby} and \textbf{FastR}
+in one JVM. \textbf{Galaaz 2.0} is a different architecture:
+\textbf{JRuby or CRuby} talk to \textbf{standard GNU R} over a process
+bridge we call \textbf{NewBridge}. You keep CRAN and Bioconductor
+(including compiled packages), and you keep a normal Ruby toolchain.
+
+This post is the 2.0 story: what changed, how the bridge works, how to
+pin R versions in containers, how data moves (including \textbf{Apache
+Arrow}), and how to keep the bridge free for long R jobs. Deep API
+detail lives in the \href{https://rbotafogo.github.io/galaaz/}{Galaaz
+Manual}; here we stay at blog length with a few runnable sketches.
+
+\section{What changed}\label{what-changed}
+
+{\def\LTcaptype{none} % do not increment counter
+\begin{longtable}[]{@{}
+  >{\raggedright\arraybackslash}p{(\linewidth - 4\tabcolsep) * \real{0.3333}}
+  >{\raggedright\arraybackslash}p{(\linewidth - 4\tabcolsep) * \real{0.3333}}
+  >{\raggedright\arraybackslash}p{(\linewidth - 4\tabcolsep) * \real{0.3333}}@{}}
+\toprule\noalign{}
+\begin{minipage}[b]{\linewidth}\raggedright
+\end{minipage} & \begin{minipage}[b]{\linewidth}\raggedright
+Historical stack
+\end{minipage} & \begin{minipage}[b]{\linewidth}\raggedright
+Galaaz 2.0
+\end{minipage} \\
+\midrule\noalign{}
+\endhead
+\bottomrule\noalign{}
+\endlastfoot
+Ruby & TruffleRuby (Graal) & \textbf{JRuby} or \textbf{CRuby} \\
+R & FastR (subset of GNU R) & \textbf{GNU R} (CRAN / Bioconductor) \\
+Coupling & Same-JVM interop & \textbf{NewBridge} (separate processes) \\
+Install & Special Graal distribution & \texttt{gem\ install} + compile
+gatekeeper \\
+Legacy tools & \texttt{grun}, polyglot \texttt{gknit-draft} &
+\texttt{bin/galaaz-ruby}, \texttt{bin/gknit} \\
+\end{longtable}
+}
+
+Ideas from the older articles still matter --- ggplot layers, dplyr
+pipes, gKnit literate docs --- but the \textbf{engine} underneath is
+different. If you land on a 2018 ``Ruby + R on GraalVM'' post, treat the
+plots and narrative as inspiration and this post (plus the manual) as
+the current stack.
+
+\section{NewBridge in one picture}\label{newbridge-in-one-picture}
+
+Galaaz 2.0 does \textbf{not} embed Renjin or FastR. Roughly:
+
+\begin{enumerate}
+\def\labelenumi{\arabic{enumi}.}
+\tightlist
+\item
+  Your \textbf{Ruby} process (JRuby or CRuby) loads Galaaz.
+\item
+  A native \textbf{gatekeeper} (\texttt{ext/new\_bridge}, Rcpp / C++)
+  mediates the protocol.
+\item
+  A \textbf{GNU R} process evaluates calls, holds large objects, and
+  runs packages.
+\end{enumerate}
+
+Ruby stays Ruby: \texttt{R.mean}, \texttt{E.aes}, method chaining,
+classes and modules. R stays R: the same \texttt{lm}, \texttt{DESeq2},
+or \texttt{ggplot2} you would run in RStudio. Large panels should
+usually \textbf{stay in R}; Ruby orchestrates and pulls small results
+(Remote Control). Opt in to unbox scalars when you need a plain Ruby
+number (\texttt{\textgreater{}\textgreater{}\ 0} for length-1 vectors is
+the common 2.0 idiom).
+
+A minimal session looks like this:
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\FunctionTok{require} \VerbatimStringTok{\textquotesingle{}galaaz\textquotesingle{}}
+
+\FunctionTok{puts} \ConstantTok{R}\AttributeTok{.sum}\NormalTok{(}\ConstantTok{R}\AttributeTok{.c}\NormalTok{(}\DecValTok{1}\NormalTok{, }\DecValTok{2}\NormalTok{, }\DecValTok{3}\NormalTok{, }\DecValTok{4}\NormalTok{, }\DecValTok{5}\NormalTok{))}
+\NormalTok{mtcars }\OperatorTok{=} \OperatorTok{\textasciitilde{}}\ConstantTok{R}\KeywordTok{[}\WarningTok{:mtcars}\KeywordTok{]}
+\FunctionTok{puts}\NormalTok{ mtcars}\AttributeTok{.dim}
+\FunctionTok{puts} \ConstantTok{R}\AttributeTok{.summary}\NormalTok{(mtcars}\AttributeTok{.mpg}\NormalTok{)}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## [1] 15
+## [1] 32 11
+##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
+##   10.40   15.43   19.20   20.09   22.80   33.90
+\end{verbatim}
+
+Callbacks still exist: Ruby procs can be registered so R code can call
+back into Ruby when a package expects an R function. That path is
+documented in the manual; the important product point is that
+\textbf{real GNU R} is on the other end of the wire.
+
+\section{Either Ruby engine}\label{either-ruby-engine}
+
+NewBridge is tested on both:
+
+\begin{itemize}
+\tightlist
+\item
+  \textbf{JRuby} (e.g.~10.x + JDK 21) --- real OS threads, JVM
+  ecosystem, natural fit for Rails under load.
+\item
+  \textbf{CRuby} (e.g.~3.3+) --- MRI gem ecosystem, familiar for many
+  Ruby shops.
+\end{itemize}
+
+The public API is the same. Launchers honor
+\textbf{\texttt{GALAAZ\_RUBY}}. Use \textbf{\texttt{bin/galaaz-ruby}},
+or \textbf{\texttt{bin/galaaz-jruby}} to force JRuby. Prefer
+\textbf{JRuby} when you want parallel Ruby threads feeding R; prefer
+\textbf{CRuby} when your app and gems already live there. Arrow helpers
+need engine-specific native bits (Java Arrow + \texttt{JAVA\_OPTS} nio
+opens on JRuby; Arrow GLib + \texttt{red-arrow} on CRuby) --- see the
+manual's Arrow section.
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\CommentTok{\# From a checkout or installed layout:}
+\ExtensionTok{bin/galaaz{-}ruby} \AttributeTok{{-}e} \DataTypeTok{\textbackslash{}}
+  \StringTok{\textquotesingle{}require "galaaz"; puts R.R\_\_version[["version.string"]]\textquotesingle{}}
+\VariableTok{GALAAZ\_RUBY}\OperatorTok{=}\NormalTok{jruby }\ExtensionTok{bin/galaaz{-}ruby} \AttributeTok{{-}e} \DataTypeTok{\textbackslash{}}
+  \StringTok{\textquotesingle{}require "galaaz"; puts R.pi\textquotesingle{}}
+\end{Highlighting}
+\end{Shaded}
+
+\section{Multiple R versions via
+containers}\label{multiple-r-versions-via-containers}
+
+Because R is a \textbf{separate process}, the Ruby gem does not
+hard-wire one R build. Whatever \texttt{R} / \texttt{Rscript} is on
+\texttt{PATH} (and can load the gatekeeper) is the R you drive. That
+makes \textbf{containers} a clean way to pin versions:
+
+\begin{itemize}
+\tightlist
+\item
+  Image A: Ubuntu + \textbf{R 4.3} + system libs for your Bioconductor
+  set.
+\item
+  Image B: same app code + \textbf{R 4.4} (or a rocker image) for
+  comparison.
+\item
+  Your Galaaz gem and Ruby code stay the same; only the image's R
+  changes.
+\end{itemize}
+
+Sketch (conceptual):
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\CommentTok{\# Dev against the R that the image provides}
+\ExtensionTok{docker}\NormalTok{ run }\AttributeTok{{-}{-}rm} \AttributeTok{{-}it}\NormalTok{ myorg/galaaz{-}r43 }\DataTypeTok{\textbackslash{}}
+\NormalTok{  bin/galaaz{-}ruby script/analysis.rb}
+
+\ExtensionTok{docker}\NormalTok{ run }\AttributeTok{{-}{-}rm} \AttributeTok{{-}it}\NormalTok{ myorg/galaaz{-}r44 }\DataTypeTok{\textbackslash{}}
+\NormalTok{  bin/galaaz{-}ruby script/analysis.rb}
+\end{Highlighting}
+\end{Shaded}
+
+Inside each image, \texttt{R\ -\/-version} differs; NewBridge still
+speaks the same protocol. For a first taste without building your own
+Dockerfile, the repo ships \textbf{try} images and runners:
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\CommentTok{\# From a Galaaz checkout}
+\ExtensionTok{./docker/try{-}gstudio/run.sh}   \CommentTok{\# JRuby + gstudio{-}oriented image}
+\ExtensionTok{./docker/try{-}cruby/run.sh}     \CommentTok{\# CRuby try image}
+\end{Highlighting}
+\end{Shaded}
+
+\textbf{Cold-install} proofs (\texttt{docker/cold-install},
+\texttt{docker/cold-install-cruby}) install the gem on a throwaway
+Ubuntu and compile the gatekeeper --- useful when you want ``empty
+machine → working bridge'' confidence. Multi-runtime Docker R matrices
+are still evolving (slow integration coverage); the sketch above is the
+pattern to build on.
+
+\section{Moving data: Apache Arrow}\label{moving-data-apache-arrow}
+
+Crossing a process boundary means you must be honest about
+\textbf{copies}. Galaaz's Arrow roadmap has three stages:
+
+{\def\LTcaptype{none} % do not increment counter
+\begin{longtable}[]{@{}
+  >{\raggedright\arraybackslash}p{(\linewidth - 4\tabcolsep) * \real{0.3333}}
+  >{\raggedright\arraybackslash}p{(\linewidth - 4\tabcolsep) * \real{0.3333}}
+  >{\raggedright\arraybackslash}p{(\linewidth - 4\tabcolsep) * \real{0.3333}}@{}}
+\toprule\noalign{}
+\begin{minipage}[b]{\linewidth}\raggedright
+Stage
+\end{minipage} & \begin{minipage}[b]{\linewidth}\raggedright
+Idea
+\end{minipage} & \begin{minipage}[b]{\linewidth}\raggedright
+Status
+\end{minipage} \\
+\midrule\noalign{}
+\endhead
+\bottomrule\noalign{}
+\endlastfoot
+\textbf{A} & Copy columnar data into R; return an R-side Arrow/proxy
+handle & Available (\texttt{from\_ruby\_batches}, \texttt{table\_from},
+\ldots) \\
+\textbf{B} & Same-machine \textbf{IPC file}: bulk bytes stay off the
+MsgPack bridge; only a \textbf{file path} crosses NewBridge & Shipped
+(two directions: B1 and B2) \\
+\textbf{C} & Shared-memory bus (true shared RAM) & Future \\
+\end{longtable}
+}
+
+Do \textbf{not} read Stage A as ``zero-copy shared RAM.'' Stage A is
+``build the table in R efficiently, then Remote-Control it.'' Stage B is
+still a file/\texttt{mmap} handoff on one machine---not Stage C---but it
+keeps large columns out of the control plane.
+
+\subsection{Stage B in plain words}\label{stage-b-in-plain-words}
+
+\textbf{IPC} here means Apache Arrow's \textbf{Inter-Process
+Communication} file format: a portable columnar dump on disk (often
+under \texttt{/dev/shm} so it lives in RAM-backed tmpfs). Ruby and R
+never shove megabytes through NewBridge; they agree on a path, then each
+side's Arrow stack reads or writes that file.
+
+Stage B splits by \textbf{direction}:
+
+\begin{itemize}
+\tightlist
+\item
+  \textbf{B1 --- Ruby → R (ingest).} Ruby writes an IPC file
+  (\texttt{Galaaz::ArrowIpc.write} / \texttt{write\_batches}). R opens
+  it with \texttt{R::Arrow.open\_ipc(path)} and gets a table proxy for
+  dplyr or modeling. After R has materialised the table, Ruby can
+  \texttt{Galaaz::ArrowIpc.release(path)} (unlink the scratch file).
+\item
+  \textbf{B2 --- R → Ruby (export).} After analytics in R,
+  \texttt{R::Arrow.write\_ipc} writes another IPC file and returns its
+  path over the bridge. Ruby reads columns or row hashes with
+  \texttt{Galaaz::ArrowIpc.read} / \texttt{read\_batches}---handy when
+  the next step is a DB write or an API payload in Ruby.
+\end{itemize}
+
+Needs: R package \texttt{arrow}, plus a Ruby writer/reader (CRuby:
+\textbf{red-arrow}; JRuby: Arrow Java JARs). Specs skip when those are
+missing; the sketch below does the same.
+
+\subsection{Stage B sketch (B1 ingest + B2
+export)}\label{stage-b-sketch-b1-ingest-b2-export}
+
+This is the path to prefer for large same-machine handoffs. Ruby threads
+build row batches; \textbf{B1} writes one IPC file and R opens it by
+path; dplyr summarises in R; \textbf{B2} writes the result IPC and Ruby
+reads row hashes. NewBridge only carries paths.
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{ipc\_ok }\OperatorTok{=} \DataTypeTok{Galaaz}\OperatorTok{::}\DataTypeTok{ArrowIpc}\AttributeTok{.available?} \OperatorTok{\&\&}
+\NormalTok{  (}\ConstantTok{R}\OperatorTok{::}\DataTypeTok{Support}\AttributeTok{.eval}\NormalTok{(}
+    \StringTok{"requireNamespace(\textquotesingle{}arrow\textquotesingle{}, quietly=TRUE) \&\& "} \OperatorTok{+}
+    \StringTok{"requireNamespace(\textquotesingle{}dplyr\textquotesingle{}, quietly=TRUE)"}\NormalTok{) }\OperatorTok{==} \DecValTok{true}\NormalTok{)}
+\ControlFlowTok{unless}\NormalTok{ ipc\_ok}
+  \FunctionTok{puts} \VerbatimStringTok{\textquotesingle{}(Skip: need Arrow IPC backend + R arrow/dplyr.)\textquotesingle{}}
+\ControlFlowTok{else}
+\NormalTok{  thread\_count }\OperatorTok{=} \DecValTok{2}
+\NormalTok{  rows\_per\_thread }\OperatorTok{=} \DecValTok{250}
+\NormalTok{  group\_count }\OperatorTok{=} \DecValTok{5}
+\NormalTok{  batches }\OperatorTok{=} \KeywordTok{[]}
+\NormalTok{  mutex }\OperatorTok{=} \DataTypeTok{Mutex}\AttributeTok{.new}
+\NormalTok{  threads }\OperatorTok{=} \KeywordTok{[]}
+
+\NormalTok{  thread\_count}\AttributeTok{.times} \ControlFlowTok{do} \OperatorTok{|}\NormalTok{tid}\OperatorTok{|}
+\NormalTok{    threads }\OperatorTok{\textless{}\textless{}} \DataTypeTok{Thread}\AttributeTok{.new} \ControlFlowTok{do}
+\NormalTok{      start }\OperatorTok{=}\NormalTok{ tid }\OperatorTok{*}\NormalTok{ rows\_per\_thread}
+\NormalTok{      local }\OperatorTok{=}\NormalTok{ (start}\OperatorTok{...}\NormalTok{(start }\OperatorTok{+}\NormalTok{ rows\_per\_thread))}\AttributeTok{.map} \ControlFlowTok{do} \OperatorTok{|}\NormalTok{i}\OperatorTok{|}
+        \OperatorTok{\{}
+          \WarningTok{id:}\NormalTok{ i,}
+          \WarningTok{grp:} \StringTok{"g}\SpecialCharTok{\#\{}\NormalTok{i }\OperatorTok{\%}\NormalTok{ group\_count}\SpecialCharTok{\}}\StringTok{"}\NormalTok{,}
+          \WarningTok{value:}\NormalTok{ (i }\OperatorTok{\%} \DecValTok{17}\NormalTok{) }\OperatorTok{+} \DecValTok{1}\NormalTok{,}
+          \WarningTok{weight:}\NormalTok{ ((i }\OperatorTok{\%} \DecValTok{5}\NormalTok{) }\OperatorTok{+} \DecValTok{1}\NormalTok{) }\OperatorTok{*} \FloatTok{0.5}
+        \OperatorTok{\}}
+      \ControlFlowTok{end}
+\NormalTok{      mutex}\AttributeTok{.synchronize} \OperatorTok{\{}\NormalTok{ batches }\OperatorTok{\textless{}\textless{}}\NormalTok{ local }\OperatorTok{\}}
+    \ControlFlowTok{end}
+  \ControlFlowTok{end}
+\NormalTok{  threads}\AttributeTok{.each}\NormalTok{(}\OperatorTok{\&}\WarningTok{:join}\NormalTok{)}
+
+\NormalTok{  paths }\OperatorTok{=} \KeywordTok{[]}
+  \ControlFlowTok{begin}
+    \CommentTok{\# B1: Ruby → IPC file → R table proxy}
+    \CommentTok{\# write\_batches wants flat row Hashes (not nested batches)}
+\NormalTok{    in\_path }\OperatorTok{=} \DataTypeTok{Galaaz}\OperatorTok{::}\DataTypeTok{ArrowIpc}\AttributeTok{.write\_batches}\NormalTok{(batches}\AttributeTok{.flatten}\NormalTok{)}
+\NormalTok{    paths }\OperatorTok{\textless{}\textless{}}\NormalTok{ in\_path}
+\NormalTok{    tbl }\OperatorTok{=} \ConstantTok{R}\OperatorTok{::}\DataTypeTok{Arrow}\AttributeTok{.open\_ipc}\NormalTok{(in\_path)}
+    \FunctionTok{puts} \StringTok{"R class: }\SpecialCharTok{\#\{}\NormalTok{tbl}\AttributeTok{.rclass}\SpecialCharTok{\}}\StringTok{"}
+    \FunctionTok{puts} \StringTok{"IPC in: }\SpecialCharTok{\#\{}\DataTypeTok{File}\AttributeTok{.basename}\NormalTok{(in\_path)}\SpecialCharTok{\}}\StringTok{"}
+
+\NormalTok{    grouped }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.dplyr\_\_\_group\_by}\NormalTok{(tbl, }\WarningTok{:grp}\NormalTok{)}
+\NormalTok{    summed }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.dplyr\_\_\_summarise}\NormalTok{(}
+\NormalTok{      grouped,}
+      \WarningTok{n:} \ConstantTok{E}\AttributeTok{.n}\NormalTok{(),}
+      \WarningTok{total:} \ConstantTok{E}\AttributeTok{.sum}\NormalTok{(}\WarningTok{:value}\NormalTok{),}
+      \WarningTok{wsum:} \ConstantTok{E}\AttributeTok{.sum}\NormalTok{(}\ConstantTok{R}\KeywordTok{[}\WarningTok{:value}\KeywordTok{]} \OperatorTok{*} \ConstantTok{R}\KeywordTok{[}\WarningTok{:weight}\KeywordTok{]}\NormalTok{)}
+\NormalTok{    )}
+
+    \CommentTok{\# B2: R → IPC file → Ruby row hashes}
+\NormalTok{    out\_path }\OperatorTok{=} \ConstantTok{R}\OperatorTok{::}\DataTypeTok{Arrow}\AttributeTok{.write\_ipc}\NormalTok{(summed)}
+\NormalTok{    paths }\OperatorTok{\textless{}\textless{}}\NormalTok{ out\_path}
+\NormalTok{    rows }\OperatorTok{=} \DataTypeTok{Galaaz}\OperatorTok{::}\DataTypeTok{ArrowIpc}\AttributeTok{.read\_batches}\NormalTok{(out\_path)}
+    \FunctionTok{puts} \StringTok{"IPC out: }\SpecialCharTok{\#\{}\DataTypeTok{File}\AttributeTok{.basename}\NormalTok{(out\_path)}\SpecialCharTok{\}}\StringTok{"}
+\NormalTok{    rows}\AttributeTok{.first}\NormalTok{(}\DecValTok{5}\NormalTok{)}\AttributeTok{.each} \ControlFlowTok{do} \OperatorTok{|}\NormalTok{r}\OperatorTok{|}
+      \FunctionTok{puts} \StringTok{"}\SpecialCharTok{\#\{}\NormalTok{r}\KeywordTok{[}\WarningTok{:grp}\KeywordTok{]}\SpecialCharTok{\}}\StringTok{ n=}\SpecialCharTok{\#\{}\NormalTok{r}\KeywordTok{[}\WarningTok{:n}\KeywordTok{]}\SpecialCharTok{\}}\StringTok{ "} \OperatorTok{+}
+           \StringTok{"total=}\SpecialCharTok{\#\{}\NormalTok{r}\KeywordTok{[}\WarningTok{:total}\KeywordTok{]}\SpecialCharTok{\}}\StringTok{ wsum=}\SpecialCharTok{\#\{}\NormalTok{r}\KeywordTok{[}\WarningTok{:wsum}\KeywordTok{]}\SpecialCharTok{\}}\StringTok{"}
+    \ControlFlowTok{end}
+
+\NormalTok{    total\_n }\OperatorTok{=}\NormalTok{ rows}\AttributeTok{.map} \OperatorTok{\{} \OperatorTok{|}\NormalTok{r}\OperatorTok{|}\NormalTok{ r}\KeywordTok{[}\WarningTok{:n}\KeywordTok{]}\AttributeTok{.to\_i} \OperatorTok{\}}\AttributeTok{.sum}
+\NormalTok{    expect\_n }\OperatorTok{=}\NormalTok{ thread\_count }\OperatorTok{*}\NormalTok{ rows\_per\_thread}
+    \FunctionTok{puts} \StringTok{"Sum of n (expect }\SpecialCharTok{\#\{}\NormalTok{expect\_n}\SpecialCharTok{\}}\StringTok{): }\SpecialCharTok{\#\{}\NormalTok{total\_n}\SpecialCharTok{\}}\StringTok{"}
+  \ControlFlowTok{ensure}
+\NormalTok{    paths}\AttributeTok{.each} \OperatorTok{\{} \OperatorTok{|}\FunctionTok{p}\OperatorTok{|} \DataTypeTok{Galaaz}\OperatorTok{::}\DataTypeTok{ArrowIpc}\AttributeTok{.release}\NormalTok{(}\FunctionTok{p}\NormalTok{) }\OperatorTok{\}}
+  \ControlFlowTok{end}
+\ControlFlowTok{end}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## R class: Table
+## IPC in: galaaz_ipc_34797_f9f16fd1b739f5ed.arrow
+## IPC out: galaaz_ipc_34797_0f200cc9e2be2726.arrow
+## g0 n=100 total=897 wsum=448.5
+## g1 n=100 total=895 wsum=895.0
+## g2 n=100 total=893 wsum=1339.5
+## g3 n=100 total=891 wsum=1782.0
+## g4 n=100 total=889 wsum=2222.5
+## Sum of n (expect 500): 500
+\end{verbatim}
+
+What to notice: \texttt{write\_batches} / \texttt{open\_ipc} is
+\textbf{B1}; after dplyr, \texttt{write\_ipc} / \texttt{read\_batches}
+is \textbf{B2}. Specs: \texttt{arrow\_ipc\_handoff\_spec.rb},
+\texttt{arrow\_ipc\_export\_spec.rb}. Deeper notes:
+\texttt{Documentation/ROADMAP\_ARROW\_RUBY\_R.md}.
+
+\subsection{Stage A (still useful)}\label{stage-a-still-useful}
+
+Stage A copies batches straight into R with
+\texttt{R::Arrow.from\_ruby\_batches}---no IPC file. Fine for modest
+tables or when you do not have a Ruby Arrow writer installed. Same
+threaded shape as above, one call instead of B1:
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{arrow\_ok }\OperatorTok{=} \ConstantTok{R}\OperatorTok{::}\DataTypeTok{Support}\AttributeTok{.eval}\NormalTok{(}
+  \StringTok{"requireNamespace(\textquotesingle{}arrow\textquotesingle{}, quietly=TRUE) \&\& "} \OperatorTok{+}
+  \StringTok{"requireNamespace(\textquotesingle{}dplyr\textquotesingle{}, quietly=TRUE)"}\NormalTok{)}
+\ControlFlowTok{unless}\NormalTok{ arrow\_ok }\OperatorTok{==} \DecValTok{true}
+  \FunctionTok{puts} \VerbatimStringTok{\textquotesingle{}(Skip: need arrow + dplyr in R.)\textquotesingle{}}
+\ControlFlowTok{else}
+\NormalTok{  batches }\OperatorTok{=} \KeywordTok{[}
+    \KeywordTok{[}\OperatorTok{\{} \WarningTok{id:} \DecValTok{1}\NormalTok{, }\WarningTok{grp:} \CharTok{\textquotesingle{}a\textquotesingle{}}\NormalTok{, }\WarningTok{value:} \DecValTok{10}\NormalTok{, }\WarningTok{weight:} \FloatTok{1.0} \OperatorTok{\}}\NormalTok{,}
+     \OperatorTok{\{} \WarningTok{id:} \DecValTok{2}\NormalTok{, }\WarningTok{grp:} \CharTok{\textquotesingle{}b\textquotesingle{}}\NormalTok{, }\WarningTok{value:} \DecValTok{20}\NormalTok{, }\WarningTok{weight:} \FloatTok{0.5} \OperatorTok{\}}\KeywordTok{]}\NormalTok{,}
+    \KeywordTok{[}\OperatorTok{\{} \WarningTok{id:} \DecValTok{3}\NormalTok{, }\WarningTok{grp:} \CharTok{\textquotesingle{}a\textquotesingle{}}\NormalTok{, }\WarningTok{value:} \DecValTok{30}\NormalTok{, }\WarningTok{weight:} \FloatTok{1.5} \OperatorTok{\}}\KeywordTok{]}
+  \KeywordTok{]}
+\NormalTok{  tbl }\OperatorTok{=} \ConstantTok{R}\OperatorTok{::}\DataTypeTok{Arrow}\AttributeTok{.from\_ruby\_batches}\NormalTok{(batches)}
+  \FunctionTok{puts} \StringTok{"R class: }\SpecialCharTok{\#\{}\NormalTok{tbl}\AttributeTok{.rclass}\SpecialCharTok{\}}\StringTok{"}
+\NormalTok{  grouped }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.dplyr\_\_\_group\_by}\NormalTok{(tbl, }\WarningTok{:grp}\NormalTok{)}
+\NormalTok{  summarised }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.dplyr\_\_\_summarise}\NormalTok{(}
+\NormalTok{    grouped, }\WarningTok{n:} \ConstantTok{E}\AttributeTok{.n}\NormalTok{(), }\WarningTok{total:} \ConstantTok{E}\AttributeTok{.sum}\NormalTok{(}\WarningTok{:value}\NormalTok{))}
+\NormalTok{  out }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.dplyr\_\_\_collect}\NormalTok{(summarised)}
+  \FunctionTok{puts} \ConstantTok{R}\AttributeTok{.as\_\_data\_\_frame}\NormalTok{(out)}
+\ControlFlowTok{end}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## R class: Table
+##   grp n total
+## 1   a 2    40
+## 2   b 1    20
+\end{verbatim}
+
+Larger Stage A demos live in
+\texttt{arrow\_from\_ruby\_batches\_spec.rb} and
+\texttt{arrow\_large\_pipeline\_spec.rb} (under \texttt{specs/} /
+\texttt{slow-specs/}).
+
+\section{Keeping the bridge free}\label{keeping-the-bridge-free}
+
+Two different ``don't block'' stories:
+
+\begin{itemize}
+\tightlist
+\item
+  \textbf{\texttt{R::Async} / \texttt{R.eval\_r\_async}} --- free a
+  \textbf{Ruby} thread while the \textbf{same} bridge R process works.
+  Good for short/medium calls when you still want one R session.
+\item
+  \textbf{\texttt{R::Job}} --- run heavy work in a \textbf{child
+  \texttt{Rscript}}. The bridge stays free for other traffic. Package
+  installs (\texttt{R.install\_and\_loads}) use this path so
+  \texttt{make}/\texttt{gcc} do not wedge the gatekeeper.
+\end{itemize}
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\ControlFlowTok{begin}
+\NormalTok{  coef }\OperatorTok{=} \ConstantTok{R}\OperatorTok{::}\DataTypeTok{Job}\AttributeTok{.eval}\NormalTok{(}\OperatorTok{\textless{}\textless{}\textasciitilde{}}\ControlFlowTok{R}\DocumentationTok{) \{ |job| job.load\_rds \}}
+\DocumentationTok{    fit \textless{}{-} lm(mpg \textasciitilde{} wt, data = mtcars)}
+\DocumentationTok{    saveRDS(unname(coef(fit)), result\_path)}
+\DocumentationTok{  }\ControlFlowTok{R}
+  \FunctionTok{puts}\NormalTok{ coef}
+\ControlFlowTok{rescue} \OperatorTok{=\textgreater{}}\NormalTok{ e}
+  \FunctionTok{puts}\NormalTok{ e}\AttributeTok{.class.to\_s}
+\NormalTok{  e}\AttributeTok{.message.to\_s.scan}\NormalTok{(}\SpecialStringTok{/.\{1,68\}/}\NormalTok{)}\AttributeTok{.each} \OperatorTok{\{} \OperatorTok{|}\NormalTok{line}\OperatorTok{|} \FunctionTok{puts}\NormalTok{ line }\OperatorTok{\}}
+\ControlFlowTok{end}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## [1] 37.285126 -5.344472
+\end{verbatim}
+
+Rule of thumb: short interactive analytics on the bridge; installs and
+multi-minute fits in \textbf{\texttt{R::Job}}. Details and timeouts
+(\texttt{GALAAZ\_INSTALL\_TIMEOUT\_SEC}, \texttt{GALAAZ\_JOBS\_DIR}) are
+in the manual.
+
+\section{What stayed the same}\label{what-stayed-the-same}
+
+Galaaz 2.0 is a new \textbf{runtime}, not a new plotting language. These
+still apply:
+
+\begin{itemize}
+\tightlist
+\item
+  \textbf{ggplot2} from Ruby --- see \emph{Ruby Plotting with Galaaz} /
+  \emph{Beautiful Ruby Plots}.
+\item
+  \textbf{dplyr / NSE} --- see \emph{Non Standard Evaluation in dplyr
+  with Galaaz}.
+\item
+  \textbf{Literate docs} --- \textbf{gKnit} still wraps knitr so Ruby
+  chunks render next to R (HTML/PDF).
+\item
+  \textbf{Classes, modules, procs} --- the \emph{oh my} S4 comparison
+  still teaches structure; unwrap and bridge details follow 2.0 rules.
+\end{itemize}
+
+R-on-Rails (Ruby web + R science) is the product framing: Rails (or any
+Ruby app) orchestrates; GNU R computes.
+
+\section{Conclusion}\label{conclusion}
+
+\textbf{Galaaz 2.0} bets on \textbf{boring, powerful defaults}: standard
+Ruby engines, standard GNU R, a clear process bridge, containers to pin
+R, and Arrow-shaped paths for larger tables --- with zero-copy shared
+memory still on the roadmap. The Graal-era prototype proved the
+\emph{idea}; 2.0 makes the \emph{ecosystem} reachable.
+
+\subsection{Further reading}\label{further-reading}
+
+\begin{itemize}
+\tightlist
+\item
+  Manual (GitHub Pages): \url{https://rbotafogo.github.io/galaaz/}
+\item
+  Arrow roadmap: \texttt{Documentation/ROADMAP\_ARROW\_RUBY\_R.md}
+\item
+  Repo blogs under \texttt{blogs/} (ggplot, dplyr, gKnit, oh my, manual)
+\item
+  Try images: \texttt{docker/try-gstudio}, \texttt{docker/try-cruby}
+\item
+  Older Graal-era plot narrative (historical): search ``Ruby Plotting
+  with Galaaz in GraalVM'' on Towards Data Science
+\end{itemize}
+
+\end{document}