sodium.secure-memory: new vocab

[factor.git] / extra / sodium / sodium-docs.factor

diff --git a/extra/sodium/sodium-docs.factor b/extra/sodium/sodium-docs.factor
new file mode 100644 (file)
index 0000000..4122b86
--- /dev/null
+++ b/extra/sodium/sodium-docs.factor
@@ -0,0 +1,15 @@
+! Copyright (C) 2020 Alexander Ilin.
+! See http://factorcode.org/license.txt for BSD license.
+USING: alien help.markup help.syntax kernel sodium.ffi ;
+IN: sodium
+
+HELP: check-malloc
+{ $values
+  { "ptr" alien }
+  { "ptr/*" alien }
+}
+{ $description "Check if " { $snippet "ptr" } " is " { $snippet "null" } " and throw " { $link sodium-malloc-error } " in that case. Otherwise simply leave " { $snippet "ptr" } " as is." } ;
+
+HELP: sodium-malloc-error
+{ $description "Throws a " { $link sodium-malloc-error } " error." }
+{ $error-description "This error is thrown when " { $link sodium_malloc } " returns " { $snippet "null" } " due to memory allocation failure. Since each such allocation requires several pages of swap-protected memory, it is a limited resource in any OS." } ;