tur/arrow

(arr [^fat f])

lift a function to an arrow (identity for function arrows).

(arr (fn [x] (+ x 1)))  ; => identity for functions

(>>> [A B C])

compose two function arrows sequentially (register-class-correct).

Polymorphic over the element type: the type parameters A, B, C are bound at each call site from the declared types of f and g, so a float pipeline emits a double-returning inner body dispatched through tur_thunk_double_double_t (register-class-correct), and an int pipeline uses the standard int64 thunk ABI.

((>>> (fn [x : float] : float (+ x 1.0))
      (fn [x : float] : float (* x 2.0))) 3.0)  ; => 8.0

Since: Phase CA1

(arrow-first [^fat f])

apply a function to the first component of a Tuple2.

((arrow-first (fn [x] (+ x 1))) <heap Tuple2 (5, 10)>)  ; => Tuple2(6, 10)

(arrow-second [^fat f])

apply a function to the second component of a Tuple2.

((arrow-second (fn [x] (+ x 1))) <heap Tuple2 (5, 10)>)  ; => Tuple2(5, 11)

(par-comp [a b c d ^fat f ^fat g])

parallel composition of two functions on Tuple2 types.

((par-comp inc double) (tuple2 1 2))  ; => Tuple2(2, 4)

(arrow-split [a b c ^fat f ^fat g])

duplicate input and apply two functions, returning a Tuple2.

((arrow-split inc double) 3)  ; => Tuple2(4, 6)

(arrow-const [v])

arrow that ignores its input and always returns v.

((arrow-const 42) 999)  ; => 42

Since: Phase B2

(arrow-dup [x] :int)

arrow that duplicates its input into a Tuple2.

(tuple2-1st (arrow-dup 7))  ; => 7

Since: Phase B2

(defopaque LoopCell :int)

the fed-back d slot of an ArrowLoop, as a handle.

Carrier is :int (the erased two-slot pair carrier the arrow layer runs on), but the newtype keeps an arbitrary integer out of loop-cell-force: only a cell minted by one of the arrow-loop combinators is accepted.

Since: arrowloop-lazy-feedback

(loop-cell-of [slot :int] :LoopCell)

read slot 1 of an ArrowLoop input pair as a LoopCell.

The arrow layer erases every slot to the int64 carrier, so a looped arrow written in Turmeric receives the feedback cell as a plain int. This is the one sanctioned way back to the handle type.

(loop-cell-force (loop-cell-of d))  ; => the fed-back value

Since: arrowloop-lazy-feedback

(loop-cell-ready? [c :LoopCell] :bool)

has the fed-back value been written yet?

False exactly inside an arrow-loop run, before the looped arrow has returned its d output. arrow-loop-fix and arrow-loop-delay seed the cell up front, so it reads true there from the first call.

(if (loop-cell-ready? c) (loop-cell-force c) 0)

Since: arrowloop-lazy-feedback

(loop-cell-force [c :LoopCell] :int)

read the fed-back value out of a feedback cell.

Panics with <<loop>> when the value is not there yet -- that is the black hole, and it is a genuine error in the looped arrow (it demanded its own output). Guard with loop-cell-ready? when a miss is expected.

(let [lp (arrow-loop step)]
  (loop-cell-force (loop-cell-of (lp 7))))

Since: arrowloop-lazy-feedback

(defclass Category [arr])

the base of the arrow hierarchy: an identity arrow and sequential composition.

Since: Phase CA2

(defclass Arrow [a] [(Category a)])

lift functions into arrows and wire them together.

Since: Phase CA1

(defclass ArrowZero [a] [(Category a)])

an arrow with a distinguished empty/zero arrow.

Since: Phase CA1

(defclass ArrowPlus [a] [(ArrowZero a)])

an ArrowZero whose arrows form a monoid under choice.

Since: Phase CA1

(defclass ArrowChoice [a] [(Arrow a)])

route an arrow over one arm of a sum (Either).

Since: Phase CA1

(defclass ArrowLoop [a] [(Arrow a)])

feed part of an arrow's output back as input.

Since: Phase CA1 (lazy feedback: arrowloop-lazy-feedback)

(defclass ArrowApply [a] [(Arrow a)])

apply an arrow that is itself a value flowing through.

Since: Phase CA1

(definstance Arrow [(->)])

the function arrow: arr is the identity (a plain function is already an arrow), >>> / <<< are composition, first / second act on a heap pair.

(definstance ArrowChoice [(->)])

map an arrow over one arm of an Either, passing the other arm through; +++ fans two arrows over the two arms, ||| collapses them.

(definstance ArrowLoop [(->)])

lazy (knot-tying) feedback: run the arrow on (b, empty-cell), fill the cell with the d output, project the c output.

(arrow-loop-lazy [^fat f] :ptr<void>)

the bare-surface twin of the ArrowLoop [(->)] instance.

Feeds the d output back through a LoopCell that is filled only once the looped arrow returns. Reads of the cell that the arrow defers -- by parking the handle in its own c output -- observe the d that this same run produced; a read made during the run is the <<loop>> black hole.

;; f parks the cell in c, so forcing c after the loop yields d = b * 10.
(let [lp (arrow-loop-lazy park-cell-step)]
  (loop-cell-force (loop-cell-of (lp 7))))  ; => 70

Since: arrowloop-lazy-feedback

(arrow-loop-fix [^fat f d0 :int fuel :int] :ptr<void>)

feedback by iteration to a fixpoint.

For a looped arrow that reads d *strictly*: the cell is seeded with d0 and the arrow is re-run, each time seeing the previous run's d, until d stops changing or fuel iterations have elapsed. The result is the c output of the last iteration. Non-convergence is not an error here -- it simply spends the fuel and returns the last c -- so a diverging arrow costs a bounded amount of work rather than hanging.

;; newton-step: d' = (d + b/d)/2, c = d  -- integer sqrt by fixpoint.
((arrow-loop-fix newton-step 1 32) 144)  ; => 12

Since: arrowloop-lazy-feedback

(arrow-loop-delay [^fat f d0 :int] :ptr<void>)

feedback through a unit delay (step-indexed).

The fed-back component persists across calls: call n sees the d that call n-1 produced, and the first call sees d0. This is the always-total member of the family -- there is no black hole and no iteration -- and it is the feedback shape signal-processing and state-machine arrows want, where the loop is closed over time rather than within a single step.

The returned arrow is stateful: it owns one cell, so each call advances the same feedback line. Call arrow-loop-delay again for an independent line.

;; sum-step: d' = d + b, c = d + b  -- a running total.
(let [acc (arrow-loop-delay sum-step 0)]
  (acc 1) (acc 2) (acc 3))  ; => 1, 3, 6

Since: arrowloop-lazy-feedback

(definstance ArrowApply [(->)])

the apply arrow: run the arrow in slot 0 on slot 1.

(definstance Category [(->)])

the function arrow: ident is the plain identity function, comp is forward composition. The eta-expanded (fn [x] x) (rather than a bare identity reference) is required so the dispatched nullary call keeps a concrete result type -- see docs/archive/history/instance-method-returning-untyped-param-loses-result-type.md.