c96e9a3 · rowtype-yoga/purescript-arraybuffer-builder

git.iko.soy/rowtype-yoga/purescript-arraybuffer-builder

on master help sign in

docs

c96e9a3James Brock6 years ago

README.md+9−1

compare with master

unifiedsplit

@@ -10,7 +10,9 @@ equivalent to types of the same name in the Haskell

10[`Data.Binary.Put`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html)

11module.

13−This package defines no typeclasses. Typeclass-based

13+This package defines

14+[no typeclasses](http://code.slipthrough.net/2018/03/13/thoughts-on-typeclass-codecs/).

15+Typeclass-based

14serialization/deserialization generally assumes that we are round-tripping

16serialization/deserialization generally assumes that we are round-tripping

15some data structures out to storage and then back into our program.

17some data structures out to storage and then back into our program.

16This package is designed for the case in which we are serializing some data

18This package is designed for the case in which we are serializing some data

@@ -90,3 +92,9 @@ putArrayInt32 xs = do

90do

92do

91 arraybuffer <- execPut $ putArrayInt32 [1,2,3]

93 arraybuffer <- execPut $ putArrayInt32 [1,2,3]

92```

94```

95+

96+

97+## Alternative packages for `ArrayBuffer` serialization

98+

99+* https://pursuit.purescript.org/packages/purescript-node-buffer

100+* https://pursuit.purescript.org/packages/purescript-arraybuffer-class

src/Data/ArrayBuffer/Builder.purs+70−74

@@ -325,77 +325,73 @@ putFloat64le :: forall m. (MonadEffect m) => Number -> PutM m Unit

325putFloat64le = putArrayBuffer <=< encodeFloat64le

326

327

328−-- | ## Implementation Details

328+-- ## Implementation Details

329−-- |

329+--

330−-- | We want our `Builder` to be a data structure with

330+-- We want our `Builder` to be a data structure with

331−-- | * *O(1)* monoid append

331+-- * *O(1)* monoid append

332−-- | * *O(n)* fold

332+-- * *O(n)* fold

333−-- |

333+--

334−-- | Our `Builder` implementation is an unbalanced binary tree.

334+-- Our `Builder` implementation is an unbalanced binary tree.

335−-- |

335+--

336−-- | For monoid `append`, what we actually get is *O(1)* when either the

336+-- For monoid `append`, what we actually get is *O(1)* when either the

337−-- | left or right tree is a singleton. If that's not true, then in the

337+-- left or right tree is a singleton. If that's not true, then in the

338−-- | unlikely worst case `append` might be *O(n)*.

338+-- unlikely worst case `append` might be *O(n)*.

339−-- |

339+--

340−-- | `Builder` is optimized what we consider to be normal usage, that is,

340+-- `Builder` is optimized what we consider to be normal usage, that is,

341−-- | `snoc`ing singleton elements to the end of the `Builder`.

341+-- `snoc`ing singleton elements to the end of the `Builder`.

342−-- |

342+--

343−-- | If a Builder is built entirely by `snoc`ing, it will look like a

343+-- If a Builder is built entirely by `snoc`ing, it will look like a

344−-- | left-only binary tree, a.k.a. a linked list.

344+-- left-only binary tree, a.k.a. a linked list.

345−-- |

345+--

346−-- | ```

346+-- ```

347−-- | ④

347+-- ④

348−-- | ╱

348+-- ╱

349−-- | ③

349+-- ③

350−-- | ╱

350+-- ╱

351−-- | ②

351+-- ②

352−-- | ╱

352+-- ╱

353−-- | ①

353+-- ①

354−-- | ```

354+-- ```

355−-- |

355+--

356−-- | If two of these `snoc`-built trees are `append`ed, then the new tree

356+-- If two of these `snoc`-built trees are `append`ed, then the new tree

357−-- | will look like

357+-- will look like

358−-- |

358+--

359−-- | ```

359+-- ```

360−-- | ④

360+-- ④

361−-- | ╱ ╲

361+-- ╱ ╲

362−-- | ③ ⑧

362+-- ③ ⑧

363−-- | ╱ ╱

363+-- ╱ ╱

364−-- | ② ⑦

364+-- ② ⑦

365−-- | ╱ ╱

365+-- ╱ ╱

366−-- | ① ⑥

366+-- ① ⑥

367−-- | ╱

367+-- ╱

368−-- | ⑤

368+-- ⑤

369−-- | ```

369+-- ```

370−-- |

370+--

371−-- | This is all similar to

371+-- This is all similar to

372−-- | [__bytestring-tree-builder__](https://hackage.haskell.org/package/bytestring-tree-builder)

372+-- [__bytestring-tree-builder__](https://hackage.haskell.org/package/bytestring-tree-builder)

373−-- | , except that the

373+-- , except that the

374−-- | [`Tree`](https://hackage.haskell.org/package/bytestring-tree-builder-0.2.7.3/docs/src/ByteString.TreeBuilder.Tree.html#Tree)

374+-- [`Tree`](https://hackage.haskell.org/package/bytestring-tree-builder-0.2.7.3/docs/src/ByteString.TreeBuilder.Tree.html#Tree)

375−-- | structure in __bytestring-tree-builder__ only carries values in its

375+-- structure in __bytestring-tree-builder__ only carries values in its

376−-- | leaves, which is how it achieves *O(1)* appending, at the cost of

376+-- leaves, which is how it achieves *O(1)* appending, at the cost of

377−-- | a higher coefficient time factor on the fold.

377+-- a higher coefficient time factor on the fold.

378−-- |

378+--

379−-- | We hope that this implementation is fairly fast, but we

379+-- We hope that this implementation is fairly fast, but we

380−-- | haven't chosen this implementation because it's fast, we've chosen

380+-- haven't chosen this implementation because it's fast, we've chosen

381−-- | this implementation because it's simple.

381+-- this implementation because it's simple.

382−-- | If someone wants to create a fast Purescript ArrayBuffer serialization

382+-- If someone wants to create a fast Purescript ArrayBuffer serialization

383−-- | library, then they can benchmark against this one to prove that the new

383+-- library, then they can benchmark against this one to prove that the new

384−-- | one is fast.

384+-- one is fast.

385−-- |

385+--

386−-- | One relatively cheap and simple performance improvement for this library would be to

386+-- One relatively cheap and simple performance improvement for this library would be to

387−-- | remove the Null constructor of `Builder` and instead use Javascript nulls.

387+-- remove the Null constructor of `Builder` and instead use Javascript nulls.

388−-- |

388+--

389−-- | In the longer term, it might make sense to try to change the Builder so

389+-- In the longer term, it might make sense to try to change the Builder so

390−-- | that it works like the

390+-- that it works like the

391−-- | https://hackage.haskell.org/package/bytestring/docs/Data-ByteString-Builder.html

391+-- https://hackage.haskell.org/package/bytestring/docs/Data-ByteString-Builder.html

392−-- |

392+--

393−-- | Here are some benchmarks of different Haskell ByteString builders

393+-- Here are some benchmarks of different Haskell ByteString builders

394−-- | https://github.com/haskell-perf/strict-bytestring-builders

394+-- https://github.com/haskell-perf/strict-bytestring-builders

395−-- |

395+--

396−-- | We've tried to design the API for this library with minimal assumptions,

396+-- We've tried to design the API for this library with minimal assumptions,

397−-- | so that if we want to change the Builder implementation later then we can.

397+-- so that if we want to change the Builder implementation later then we can.

398−-- |

399−-- | Alternatives

400−-- | https://pursuit.purescript.org/packages/purescript-node-buffer

401−-- | https://pursuit.purescript.org/packages/purescript-arraybuffer-class