sodium.secure-memory: fix a stack effect and add documentation

diff --git a/extra/sodium/secure-memory/secure-memory-docs.factor b/extra/sodium/secure-memory/secure-memory-docs.factor
index a6f802f6256e56362c26b72fd1dab7e6526ecbfa..21cb2924b7a2faf036962b4f9e3d0cbb85b55c53 100644 (file)
--- a/extra/sodium/secure-memory/secure-memory-docs.factor
+++ b/extra/sodium/secure-memory/secure-memory-docs.factor
@@ -9,7 +9,7 @@ ABOUT: "sodium.secure-memory"
 ARTICLE: "sodium.secure-memory" "Secure memory"
 "The " { $vocab-link "sodium.secure-memory" } " vocab provides a simple wrapper around some of the libsodium's Secure memory functions, see " { $url "https://libsodium.gitbook.io/doc/memory_management" } "." $nl
 "The class for securely allocated alien memory:"
-{ $subsections secure-memory new-secure-memory }
+{ $subsections secure-memory new-secure-memory with-new-secure-memory }
 "Temporary memory access combinators:"
 { $subsections with-read-access with-write-access }
 "Memory access restriction setters:"
@@ -32,6 +32,15 @@ HELP: new-secure-memory
   "In case the memory could not be allocated, " { $link sodium-malloc-error } " is thrown." $nl
   "Initial memory contents are not zero, see documentation at " { $url "https://libsodium.gitbook.io/doc/memory_management" } ". The memory is initially in the read-write mode, but is protected against swapping out by the OS (if supported) and against out of boundary access. Call " { $link allow-no-access } " to restrict access after your own initialization." } ;
 
+HELP: with-new-secure-memory
+{ $values
+  { "size" number }
+  { "quot" { $quotation ( ..a secure-memory -- ..b ) } }
+}
+{ $description "Call " { $snippet "quot" } " with a newly allocated " { $link secure-memory } " instance of the given " { $snippet "size" } ". When the quotation is called, the memory is writable. After the call the access is restricted using " { $link allow-no-access } ". This combinator is especially useful when you need to initialize and lock a new memory region. The " { $snippet "quot" } " should save a reference to the memory for subsequent disposal." } ;
+
+{ new-secure-memory with-new-secure-memory } related-words
+
 HELP: allow-no-access
 { $values
     { "secure-memory" secure-memory }

diff --git a/extra/sodium/secure-memory/secure-memory.factor b/extra/sodium/secure-memory/secure-memory.factor
index 1a3a315ac72beb09f62ef5244465267556fa597b..8b314c87b8ad12000b9bf3fc56f661b4310b8b5e 100644 (file)
--- a/extra/sodium/secure-memory/secure-memory.factor
+++ b/extra/sodium/secure-memory/secure-memory.factor
@@ -30,7 +30,7 @@ TUPLE: secure-memory < disposable
 : with-write-access ( ..a secure-memory quot: ( ..a secure-memory -- ..b ) -- ..b )
     over dup allow-write-access [ allow-no-access ] curry finally ; inline
 
-: with-new-secure-memory ( ..a size quot: ( ..a secure-memory -- ..b ) -- ..b secure-memory )
+: with-new-secure-memory ( ..a size quot: ( ..a secure-memory -- ..b ) -- ..b )
     [ new-secure-memory ] dip with-write-access ; inline
 
 : secure-memory= ( a b -- ? )