marshal.h File Reference

Boundary marshalling for host bindings (MATLAB MEX, pybind11, the JSON CLI). More...

#include <cstddef>
#include <string>
#include <vector>
#include "line/num/number.h"
#include "line/util/error.h"
#include "line/util/matrix.h"

Include dependency graph for marshal.h:

Go to the source code of this file.

Classes
struct	line::io::ExactValue
	An exact scalar as it crosses to a host without a rational type: the two decimal integer strings, plus the double a host can use directly. More...

Namespaces
namespace	line
namespace	line::io

Functions
template<class T, class S>
Matrix< T >	line::io::from_column_major (const S *data, std::size_t rows, std::size_t cols)
	Build a Matrix from a column-major host buffer (MATLAB's mxGetPr layout, numpy's order='F').
template<class T, class S>
Matrix< T >	line::io::from_row_major (const S *data, std::size_t rows, std::size_t cols)
	Build a Matrix from a row-major host buffer (numpy's default order='C').
template<class T>
void	line::io::to_column_major (const Matrix< T > &m, double *out)
	Write a Matrix into a column-major host buffer, as doubles.
template<class T>
void	line::io::to_host (const std::vector< T > &v, double *out)
	Write a vector into a host buffer, as doubles.
template<class T>
std::string	line::io::exact_numerator (const T &)
	Numerator of an exact value as a decimal string; empty for inexact types.
template<class T>
std::string	line::io::exact_denominator (const T &)
template<class T>
ExactValue	line::io::marshal_scalar (const T &v)
	Marshal any T; only the exact instantiation fills numerator/denominator.
template<>
std::string	line::io::exact_numerator< Rational > (const Rational &v)
template<>
std::string	line::io::exact_denominator< Rational > (const Rational &v)
const char *	line::io::error_id (const Error &e)
	Stable identifier for an error, for mexErrMsgIdAndTxt and for mapping to a host exception class.

Detailed Description

Boundary marshalling for host bindings (MATLAB MEX, pybind11, the JSON CLI).

Three things every binding needs and none of them should reinvent:

1. COLUMN-MAJOR INGEST AND EGRESS. MATLAB hands out column-major buffers and numpy's default is row-major; the port stores row-major. A transpose is unavoidable in one direction, so it is done once here, explicitly, rather than by every gateway. Note the honest cost: this is a copy, not a view. It is O(m n) against algorithms that are O(m n) at best and usually far worse (the convolution is O(prod(N+1) M R), the LU O(n^3)), so the copy is not the term that matters. Claiming zero copy here would be a lie that only pays off for a caller that never runs an algorithm.
2. EXACT VALUES ACROSS A DOUBLE BOUNDARY. Neither MATLAB nor numpy has a rational type. An exact result therefore crosses as the pair of decimal integer strings (numerator, denominator) plus a double approximation, so the host can rebuild it with sym(num)/sym(den) or fractions.Fraction and can see, rather than guess, that the double is a rounding of something exact.
3. ERROR IDENTITY. A host needs a stable identifier, not a prose message: mexErrMsgIdAndTxt takes an id, and a Python binding maps the id to an exception class. The mapping lives here so all bindings agree.

Definition in file marshal.h.