Add Memory Notes to README
This commit is contained in:
parent
36a21d5cd1
commit
0cc1aa268b
|
@ -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`.
|
17
README.md
17
README.md
|
@ -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/).
|
||||
|
||||
|
|
Loading…
Reference in New Issue