View source for LibSR:Prototype

=Overview=
The ''LibSR prototype'' is the iteration after the proof of concept. It is supposed to be "the real deal" and address the (many) shortcomings of the [[LibSR:Proof of concept|P.O.C.]]; Due to the "research" nature of the project (I don't know what will actually work best) the priority will be creating something that can easily be changed or modified to do something a certain way. One thing for example that was impossible without ''significant'' modifications to the proof of concept was multi-threading (or doing anything in an order different to "take 3 vertices {{M|\rightarrow}} rasterise the triangle"), these will be lifted.
==Key points==
# LibSR handles its own memory. In the POC memory could be shared between the program and LibSR (which is okay as it was single threaded), and it just used new/delete. In this version memory will be allocated in some way controlled by LibSR.
#* A long term and low priority goal is to have a single pool, say {{C|256mb}} (or whatever) that LibSR uses for everything.
{{Todo|Proof read page}} 
==Tasks==
===Testing===
# A "bad luck" build mode. This is a build where "luck" plays no part in not tripping assertions. For example, {{C|malloc}}/{{C|free}} usually allocates you a block aligned to a {{M|4\text{kb} }} boundary (that to the implementation is a 4kb allocation), this means just by "luck" things can be aligned when they are not allocated by something aware of the alignment requirements. Bad luck will align allocations to the minimum they specify, if no alignment is required, then it shall use an odd alignment.
#* See [[LibSR:Bad luck mode]] for more details.
# I once had a problem with (lack of) heap corruption when writing beyond what I actually allocated, this is because the implementation for malloc deals with {{M|4\text{kb} }} blocks at a time, so if I asked for a so many bytes, I'd actually be okay to write up to 4096 bytes. This was a difficult problem to locate and it'd be useful if there could be a bad luck mode that would protect against this, possibly by padding with some unlikely pattern and ensuring it is present on deallocation for example. 
===Assertions===
# '''DONE - see [[LibSR:Assertions]]''' LibSR doesn't throw exceptions (in my primitive tests this reduces binary size by ~30% and improves speed by ~50%), it must be assumed that "almost everything" will never fail, for example every array access is valid. It would be a huge mistake to assume this. So we will need assertions, checks that can be turned on or off for the build. So {{C|disabled}} would mean no checks and {{C|enabled}} would mean (some level of checking).
#* The action to take on assertion failure is also up for debate, debug signal and a display of what actually failed would be good. 
# '''DONE - see [[LibSR:Assertions]]''' If every array access is bound checked then quite often we find ourselves doing the check which a previous check could show us was valid; not just simply the minimum to ensure no out of bounds access occurs. All this extra work is bad. Given the "no-exceptions" policy and emphasis on speed LibSR has, we need assertions which can be completely disabled for release mode.
===Memory allocation and management===
# '''DONE''' - Define an interface to a/the memory manager that allows a malloc/free style of memory management (where a pointer is given to {{C|free}} and no other information)
# '''DONE''' - Define an interface to a/the memory manager that allows a allocation like malloc but where the caller can also provide the purpose and size of the memory to the deallocation function.
#* At some point the size of the allocation being freed will have to be calculated, rather than hashing a {{C|void*}} and looking at some allocation record it's much faster if we can just be told "here's the size" - which quite often callers can find out easily if not trivially! Of course a generic {{c|malloc}}/{{C|free}} pair is still provided where free only requires a pointer.
# '''DONE - POC - needs rewrite''' - create a wrapper for {{C|malloc}}/{{C|free}} that is a LibSR memory manager. Such a wrapper must be able to provide summary statistics on the total allocated for different things.