@@ -0,0 +1,59 @@
3+We keep all modules exposed to faciliate convenient exposure of experimental
4+APIs and constructors to users. It allows users of the library to experiment
5+much more easily and carry a caveat that these APIs can change in future
6+without notice. Since everything is exposed, maintainers do not have to think
7+about what to expose as experimental and what remains completely hidden every
8+time something is added to the library.
10+We expose the internal modules via `Streamly.Internal` namespace to keep all
11+the internal modules together under one module tree and to have their
12+documentation also separated under one head in haddock docs.
14+Another decision point is about two choices:
16+1) Keep the implementation of all the APIs in an internal module and just
17+reexport selected APIs through the external module. The disadvantages of this
19+a) users may not be able to easily figure out what unexposed APIs are available
20+other than the ones exposed through the external module. To avoid this problem
21+we can mark the unexposed APIs in the docs with a special comment.
22+b) In tests and benchmarks we will be using internal modules to test internal
23+and unexposed APIs. Since exposed APIs are exported via both internal and
24+external modules we will have to be careful in not using the internal module
25+for testing accidentally, instead we should always be using the exposed module
26+so that we are always testing exactly the way users will be using the APIs.
28+2) Keep the implementations of unexposed modules in the internal module file
29+and exposed module in the external module file. In this approach, users can
30+easily figure out the unexposed vs exposed APIs. But maintaining this would
31+require us to move the APIs from internal to external module file whenever we
34+We choose the first approach.
38+We use the "Streamly" prefix to all the module names so that they do not
39+conflict with any other module on Hackage.
41+We have the following division under Streamly:
43+* Data: All the data structures that are immutable and make use of the GC
44+ memory to store data. These data structures are mainly useful for stream
45+ processing and not for storing data in memory for longer durations.
47+* Memory: This name space is for data structures that make use of the memory as
48+ a storage device. This is not GC allocated memory but rather pinned memory.
49+ The memory in this case is treated just like any other storage device e.g.
50+ disk drives, but faster. The data is serialized into memory. Unlike the data
51+ structure under "Data" these data structures have no impact on GC. Many of
52+ the data structures in this category are parallel to the data structures
55+* FileSystem: This name space is for data structures that reside in files
56+ provided by a file system interface on top of storage devices.
58+* Network: This name space is for APIs that access data from remote computers