neurocyte/flow-website
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Marked editor as draft

Browse source 
All the docs contained in this group of commits are marked as not draft,
except for editor, which I will be working as I get more experience and
get more precise on the various topics related to the editor and groups
of functions.
This commit is contained in:
Igor Támara 2025-10-30 23:35:53 -05:00 • committed by CJ van den Berg
parent e837a66b97
commit 0494574c36
9 changed files with 234 additions and 188 deletions
Download patch file Download diff file Expand all files Collapse all files

66
content/docs/architecture/inner_data_exchange.smd
View file

@ -13,13 +13,14 @@
Flow uses actor model to offer an snappy experience when working with
projects that have tens of thousands of source files, also features
async communication with the threads that are working in independent
tasks that contribute to have vcs, lsp and tree-sitter integration,
apart from the directory introspection to make available what is
expected from an IDE. The command arguments travel to the target
command and are en/decoded powered by
[cbor](https://github.com/neurocyte/cbor), the same as the parameters
that are sent from one thread to another. The process management is
provided by [thespian](https://github.com/neurocyte/thespian).
tasks supporting git interface, lsp and tree-sitter integration,
apart from the directory introspection to make available all the
files of the project, all of them expected s from an IDE. The
command arguments travel to the target command and are en/decoded
powered by [cbor](https://github.com/neurocyte/cbor), the same as the
parameters that are sent from one thread to another. The process
management is provided by
[thespian](https://github.com/neurocyte/thespian).
This chapter describes the mechanisms that flow has to pass arguments
between components.
@ -41,20 +42,20 @@ variables
message is encoded and must be copied somewhere for more permanent
storage, or possibly sent somewhere via thespian.
* Decoding happens via the `cbor.match`, `cbor.extract` and
`cbor.extractAlloc` group of functions. `cbor.extract` functions do not
allocate and cannot be used to extract some types that require allocation.
`cbor.extractAlloc` group of functions. `cbor.extract` functions do
not allocate and cannot be used to extract some types that require allocation.
`cbor.extractAlloc` functions _do_ allocate and can extract arrays and
structures that require allocation. Both `cbor.extract` and
`cbor.extractAlloc` produce strings that **reference** the original CBOR
data buffer. `thespian.message.match` and `thespian.extract` functions
are fairly simple wrappers.
The most basic example on deserialization of an integer value can is shown
The most basic example on deserialization of an integer value is shown
in [commands](/docs/architecture/command#command_arguments).
Cbor features en/decoding arrays, json and compounds of basic types and the
only requirement is to decode in the same order as encoding the data, more
samples on using cbor can be seen in
Cbor features en/decoding arrays, json and compounds of basic types and
the only requirement is to decode in the same order as encoding the
data, more samples on using cbor can be seen in
[cbor tests](https://github.com/neurocyte/cbor/blob/master/test/tests.zig).
For example, when interacting with the clipboard, the messages sent are
@ -64,9 +65,9 @@ multiple chunks of information,
[]($section.id('scoping'))
## Buffer scoping
CBOR structures are mostly stored in a way that avoids allocation entirely.
This is really fast, but requires that you always know where the CBOR data
you are working with is stored.
CBOR structures are mostly stored in a way that avoids allocation
entirely. This is really fast, but requires that you always know where
the CBOR data you are working with is stored.
* Received messages are read directly from the thespian process (actor)
receive buffer and remain in scope only for the duration of an actor's
@ -86,30 +87,27 @@ All of this implies several things worth keeping in mind:
* `thespian.pid.send` will encode it's parameters to
`thespian.message_buffer` and then send them to the destination actor's
receive buffer. This will invalidate the contents of
`thespian.message_buffer` and destroy any message previously encoded with
`thespian.message.fmt` (on the same thread).
* Calling `command.fmt` inside a command that uses `command.Context.args`
will possibly invalidate the command's own arguments. I say _possibly_
because the `ctx.arg` may come from somewhere else entirely, like the
actor's receive buffer if the command was called remotely, or some other
explicitly allocated buffer.
`thespian.message_buffer` and destroy any message previously encoded
with `thespian.message.fmt` (on the same thread).
* Calling `command.fmt` inside a command that uses
`command.Context.args` will possibly invalidate the command's own
arguments. I say _possibly_ because the `ctx.arg` may come from
somewhere else entirely, like the actor's receive buffer if the command
was called remotely, or some other explicitly allocated buffer.
* Use `*.fmtbuf` to encode to different buffer if there may be scoping
issues. You can allocate and scope this buffer any way you want.
* Calling `thespian.exit_message` while propagating an error up the stack
that was previously created with `thespian.exit_message` will overwrite the
original error
* Don't ever try to free a CBOR buffer unless you know exactly where it came
from.
* Strings extracted from CBOR buffers are **references** into the original
CBOR data and will be invalidated implicitly when the CBOR buffer they came
from is invalidated/overwritten.
* Calling `thespian.exit_message` while propagating an error up the
stack that was previously created with `thespian.exit_message` will
overwrite the original error
* Don't ever try to free a CBOR buffer unless you know exactly where it
came from.
* Strings extracted from CBOR buffers are **references** into the
original CBOR data and will be invalidated implicitly when the CBOR
buffer they came from is invalidated/overwritten.
[]($section.id('next'))
## Next steps
Serialization and deserialization occurs almost everywhere
* [Editor](/docs/architecture/editor)
* [Commands](/docs/architecture/command)
* [Minimodes](/docs/architecture/minimode)
* [Architecture](/docs/architecture)