Add Memory Notes to README

This commit is contained in:
Sarah Jamie Lewis 2023-02-23 10:16:59 -08:00
parent 36a21d5cd1
commit 0cc1aa268b
2 changed files with 41 additions and 3 deletions

27
MEMORY.md Normal file
View File

@ -0,0 +1,27 @@
# Memory Model
This document provides an overview of the memory model of libCwtch. Callers should consult this document to ensure
that they are properly handling pointers passed to-and-from libCwtch.
## Pointer Parameters
All pointers **passed** into functions in this library, except `c_FreePointer`, are assumed to be owned by the caller.
libCwtch **will not** modifying the underlying memory, nor attempt to free or otherwise modify these pointers.
This is realized by copying the underlying memory using `C.GoStringN`. libCwtch guarantees that it will not depend
on the underlying memory of these pointers being available after returning from this function.
Callers are responsible for freeing these pointers after the call has been completed.
## Returned Pointers
All pointers **returned** by functions in libCwtch should be assumed to owned by libCwtch
Callers **must not** modifying the underlying memory of these pointers, nor attempt to free or otherwise modify these pointers
through any method other than the one provided below.
Calling functions **must** copy the contents of the memory into their own memory space and then call `c_FreePointer` providing
the returned pointer as a parameter.
libCwtch guarantees that it will not modify or free the underlying memory of these pointers prior to a call to `c_FreePointer`.

View File

@ -14,9 +14,9 @@ Supported function prototypes:
* `app <Function Name> <Args>` - an application-level function, called on global `Application`
* `profile <Function Name> <Args>` - a profile-level function, takes `profile` as an implicit first argument
* `json(profile) <Function Name> <Args>` - a profile-level function, takes `profile` as an implicit first argument and returns a json blob that must be freed by the calling library
* `json(profile) <Function Name> <Args>` - a profile-level function, takes `profile` as an implicit first argument and returns a json blob that must be freed by the calling library (see [MEMORY](./MEMORY.md))
* `@profile-experiment <Function Name> <Experiment> <Args>`- an experimental profile-level function, takes `profile` as an implicit first argument, experiment must implement cwtch Functionality interface
* `@(json)profile-experiment <Function Name> <Experiment> <Args>` - am experimental profile-level function, takes `profile` as an implicit first argument and returns a json blob that must be freed by the calling library, , experiment must implement cwtch Functionality interface
* `@(json)profile-experiment <Function Name> <Experiment> <Args>` - am experimental profile-level function, takes `profile` as an implicit first argument and returns a json blob that must be freed by the calling (see [MEMORY](./MEMORY.md)) library, , experiment must implement cwtch Functionality interface
Supported argument prototypes:
@ -32,4 +32,15 @@ All arguments must be defined in the order they are specified by the underlying
Other directives:
* `import <go pkg>` - includes an additional go importin the compiled lib.go (needed for experiments)
* Functions that start with `Enhanced` are automatically stripped of that prefix for their binding names e.g. `EnhancedGetMessage` generated a binding `c_GetMessage` - for certain functions Cwtch has two potential calling options `<Function>` and `Enhanced<Function>`. "Enhanced" in this case means that the response is optimised for calling by a user-facing application by e.g. directly making a number of calls under the hood and returning a json blob of the results.
* Functions that start with `Enhanced` are automatically stripped of that prefix for their binding names e.g. `EnhancedGetMessage` generated a binding `c_GetMessage` - for certain functions Cwtch has two potential calling options `<Function>` and `Enhanced<Function>`. "Enhanced" in this case means that the response is optimised for calling by a user-facing application by e.g. directly making a number of calls under the hood and returning a json blob of the results.
## Support Cwtch Development
We couldn't do what we do without all the wonderful community support we get, from [one-off donations](https://openprivacy.ca/donate) to [recurring support via Patreon](https://www.patreon.com/openprivacy).
If you want to see us move faster on some of these goals and are in a position to, please [donate](https://openprivacy.ca/donate). If you happen to be at a company that wants to do more for the community and this aligns, please consider donating or sponsoring a developer.
Donations of **$5 or more** can opt to receive stickers as a thank-you gift!
For more information about donating to Open Privacy and claiming a thank you gift [please visit the Open Privacy Donate page](https://openprivacy.ca/donate/).