stack allocations

Author: ZeroIntensity

.gitignore

@@ -12,4 +12,5 @@ vgcore.*
 .venv/
 _pointers.cpython*
 *.egg-info/
-wheelhouse/
+wheelhouse/
+gen.py

docs/allocation.md

@@ -98,3 +98,99 @@ for index, ptr in enumerate(array):
 
 print(ptr[1])  # prints out "1"
 ```
+
+## Stack
+
+Objects can be put on the stack using `stack_alloc` or `acquire_stack_alloc`:
+
+```py
+from pointers import stack_alloc, StackAllocatedPointer
+
+@stack_alloc(28)
+def test(ptr: StackAllocatedPointer):
+    ptr <<= 1
+    print(*ptr)
+
+test()
+```
+
+The difference between `acquire_stack_alloc` and `stack_alloc` is that `acquire_stack_alloc` automatically calls the function, whereas `stack_alloc` makes you call it manually:
+
+```py
+from pointers import stack_alloc, acquire_stack_alloc, StackAllocatedPointer
+
+@stack_alloc(28)
+def a(ptr: StackAllocatedPointer):  # you need to call a manually
+    ...
+
+@acquire_stack_alloc(28)
+def b(ptr: StackAllocatedPointer):  # this is called automatically by the decorator
+    ...
+```
+
+Stack allocated pointers **cannot** be deallocated manually, meaning the following **will not** work:
+
+```py
+from pointers import acquire_stack_alloc, StackAllocatedPointer, free
+
+@acquire_stack_alloc(28)
+def test(ptr: StackAllocatedPointer):
+    free(ptr)  # ValueError is raised
+```
+
+Instead, it will be popped off the stack at the end of the function. Read more about that below.
+
+### Why not a context?
+
+**Warning:** This section is for advanced users.
+
+We have to go through a couple different reasons on why we need to use a decorator instead of a context for stack allocations.
+
+First, we need to understand how functions are handled in ASM (at least on GNU compilers).
+
+Lets take a look at this piece of x86 ASM as an example (32 bit):
+
+```asm
+global _start
+
+_start:
+    push 123 ; 123 on stack
+    call func ; call our function
+    mov eax, 1 ; system exit
+    mov ebx, 0 ; return code
+    int 0x80 ; call kernel
+
+func:
+    push ebp ; push base pointer onto the stack
+    mov ebp, esp ; preserve current stack top
+
+    mov esp, ebp
+    pop ebp ; restore base pointer
+    ret ; jump to return address
+```
+
+This function does nothing, but as you can see with the `push` and `pop` instructions, we are using the stack to pass parameters and store the return address of the functions.
+
+When we put something on the top of the stack in Python, we still need to follow these rules. The memory is popped off the stack at the end of the C function (in this case, its pointers.py's `run_stack_callback`), so we cannot use it elsewhere.
+
+Now, how does this relate to using a context or not?
+
+Python context managers are done like this:
+
+```py
+class MyContext:
+    def __enter__(self):
+        ...
+
+    def __exit__(self, *_):
+        ...
+
+with MyContext() as x:
+    ...
+```
+
+Remember, the data is popped off the stack after the end of the C function, not the Python function, meaning we can't just allocate and then store in the class. We also can't just do it all from `__enter__`, since the allocated memory will be destroyed at the end of it.
+
+We also can't do it from a C based class, since that will still have to return the object.
+
+Note that there's also no yielding in C, so we can't return early either.

docs/bindings.md

@@ -151,6 +151,40 @@ signal(2, sighandler)
 c_raise(2)  # send signal 2 to the program
 ```
 
+Alternatively, you can create a function pointer using `to_func_ptr`:
+
+```py
+from pointers import to_func_ptr, signal, exit, c_raise
+
+def test(signum: int) -> None:
+    print('hello world')
+    exit(0)
+
+signal(2, to_func_ptr(test))
+c_raise(2)
+```
+
+**Note:** `to_func_ptr` requires the function to be type hinted in order to correctly generate the signature of the C function, so the following **will not** work:
+
+```py
+def test(signum):
+    ...
+
+to_func_ptr(test)
+```
+
+## Null Pointers
+
+If you would like to pass a `NULL` pointer to a binding, you can use `pointers.NULL` or pass `None`:
+
+```py
+from pointers import time, NULL
+
+# these two do the same thing
+print(time(NULL))
+print(time(None))
+```
+
 ## Custom Bindings
 
 You can create your own binding to a C function with `ctypes` and pointers.py.

docs/cpython_bindings.md

@@ -20,7 +20,7 @@ Here's an example with `PyEval_GetFrame`:
 ```py
 from pointers import PyEval
 
-frame = PyEval.get_frame()  # calls the c PyEval_GetFrame function
+frame = PyEval.get_frame()  # calls PyEval_GetFrame
 ```
 
 ## Casting Pointers
@@ -44,11 +44,3 @@ from pointers import PyEval, struct_cast
 frame = struct_cast(PyEval.get_frame())
 # frame is now a valid frame object!
 ```
-
-## Limited Support
-
-CPython ABI bindings are still unfinished, and any method that contains one of the following remains unsupported:
-
--   Uses a format string
--   Undocumented on [python.org](https://python.org)
--   Isn't documented properly

docs/making_a_program.md renamed to docs/working_by_example.md

@@ -1,6 +1,10 @@
-# Making a Program
+# Working By Example
 
-Now that we've learned how to use pointers.py, lets build a small script to make `1 == 2`, and then revert our changes (make `1 != 2`).
+Now that we've learned how to use pointers.py, lets build some small scripts to try out some of its features.
+
+## Making one equal two
+
+**Note:** This may not work depending on your build of CPython.
 
 Lets start out with creating a pointer to `1`, and then moving `2` to it:
 
@@ -85,7 +89,3 @@ ptr <<= ~cache
 assert 1 != 2
 free(cache)
 ```
-
-**Note:** This may not work depending on your build of CPython.
-
-Congratulations, you have written a working program with pointers.py!