@@ -1,4 +1,4 @@ -Copyright (c) 2006, 2007, Charles R. Childers <charles.childers@gmail.com> +Copyright (c) 2006 - 2009, Charles R. Childers <charles.childers@gmail.com> Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above doc/LICENSE @@ -1,22 +1,20 @@ - _____ _ -|_ _|__ | | ____ _ + _____ _ +|_ _|__ | | ____ _ | |/ _ \| |/ / _` | | | (_) | < (_| | |_|\___/|_|\_\__,_| - -Toka is a programming language that draws on -my experiences with a variety of languages. -It's still experimental, so things sometimes -change significantly with little to no warning. + +Toka is a programming language that draws on my experiences +with a variety of languages. It's still experimental, so things +sometimes change significantly with little to no warning. Overall it does work suprising well though. -The language has been influenced by my -experiences with RetroForth, HelFORTH, Factor, -and other languages. In most respects it shows -a strong bias towards Forth. It does have some -extra things (quotes, garbage collection, etc) -that make programming easier for me. -================================================ +The language has been influenced by my experiences with Retro, +HelFORTH, Factor, and other languages. In most respects it +shows a strong bias towards Forth. It does have some extra +things (quotes, garbage collection, etc) that make programming +easier for me. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ BUILDING AND INSTALLATION 1) Run the configuration tool and answer the @@ -27,39 +25,46 @@ BUILDING AND INSTALLATION 2) Run "make" then "sudo make install" - This will put 'toka' into /usr/bin, and - create /usr/share/toka, where 'bootstrap.toka' - will be placed. + This will put 'toka' into /usr/bin, and create + /usr/share/toka, where 'bootstrap.toka' will be placed. - Any optional components you selected will be - built and installed as well. -================================================ + Any optional components you selected will be built and + installed as well. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ CHANGES -- Completely rewritten build system -- Ports - - Improved: BeOS - - New: Windows (Win32, not Cygwin) -- Cleanups - - Alternate stack now separate from Address - ("Return") stack - - Address stack increased to 2048 slots - - Stacks and stack pointers are now kept in - structs rather than totally separate global - variables. - - Renamings in vm_ - - Primitives are now handled differently. They - are wrapped in quotes during the initial - dictionary setup. - - Allows removal of: .PRIM_WORD, .PRIM_MACRO - - Simplified implementation of ` -- Bugfixes - - Decompiler now recognizes "` <name>" forms - - Stack comments and/or descriptions have been +Current + - Strings no longer dynamically imported by bootstrap.toka + - Removal of trailing whitespace in all source files + (not yet completed) + + +1.2 + - Completely rewritten build system + - Ports + - Improved: BeOS + - New: Windows (Win32, not Cygwin) + - Cleanups + - Alternate stack now separate from Address + ("Return") stack + - Address stack increased to 2048 slots + - Stacks and stack pointers are now kept in + structs rather than totally separate global + variables. + - Renamings in vm_ + - Primitives are now handled differently. They + are wrapped in quotes during the initial + dictionary setup. + - Allows removal of: .PRIM_WORD, .PRIM_MACRO + - Simplified implementation of ` + - Bugfixes + - Decompiler now recognizes "` <name>" forms + - Stack comments and/or descriptions have been corrected -1.1 - - Added VERSION + +1.1 + - Added VERSION - Added >string doc/README @@ -1,88 +1,74 @@ Garbage Collection in Toka +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Toka's design requires many things (quotes, strings, etc) to be +allocated dynamically. This makes manually tracking all of the +pointers and allocations tricky. - -Toka's design requires many things (quotes, -strings, etc) to be allocated dynamically. This -makes manually tracking all of the pointers and -allocations tricky. - -To work around this, there is a simple garbage -collector which is responsible for: +To work around this, there is a simple garbage collector which +is responsible for: - All memory allocations - All memory deallocation - Keeping track of all allocations -Memory allocations are done through the -gc_alloc() function. The function prototype is: +Memory allocations are done through the gc_alloc() function. +The function prototype is: gc_alloc(long items, long size, long type) -It takes a number of items (e.g., the number of -characters or cells), the size of an individual -item, and a lifespan hint (type). +It takes a number of items (e.g., the number of characters or +cells), the size of an individual item, and a lifespan hint +(type). -There are currently two hints for the lifespan -of an object. These are: +There are currently two hints for the lifespan of an object. +These are: - GC_MEM - GC_TEMP -GC_MEM is the normal one. This tells the -collector that the allocation may be permanent. -GC_TEMP is only used internally, for short-lived -allocations that are guaranteed to be safe to +GC_MEM is the normal one. This tells the collector that the +allocation may be permanent. GC_TEMP is only used internally, +for short-lived allocations that are guaranteed to be safe to collect within a short time. -The gc_alloc() function attempts to allocate the -requested amount of memory. If the allocation -fails, it collects the oldest garbage and -retries. If it still fails, ERR_NO_MEM (E1, a -fatal error) is invoked. If successful, it -updates the proper array (gc_list[] for GC_MEM, -or gc_trash[] for GC_TEMP), the total -allocations size (gc_used), and the number of -allocations currently existing (gc_objects). A -pointer to the successful allocation is left on -the data stack. - -Allocations can be marked as permanent via -gc_keep(). This has the following function -prototype: +The gc_alloc() function attempts to allocate the requested +amount of memory. If the allocation fails, it collects the +oldest garbage and retries. If it still fails, ERR_NO_MEM +(E1, a fatal error) is invoked. If successful, it updates the +proper array (gc_list[] for GC_MEM, or gc_trash[] for GC_TEMP), +the total allocations size (gc_used), and the number of +allocations currently existing (gc_objects). A pointer to the +successful allocation is left on the data stack. + +Allocations can be marked as permanent via gc_keep(). This has +the following function prototype: gc_keep() -The gc_keep() function takes a pointer from the -top of the data stack and makes that allocation -and its children permanent. +The gc_keep() function takes a pointer from the top of the data +stack and makes that allocation and its children permanent. -We cheat a bit here: Toka assumes that -allocations are done in a linear fashion. All -allocations which follow the allocation passed -to gc_keep() are treated as children. This can -lead to small memory leaks, but it seems to work -ok in practice. +We cheat a bit here: Toka assumes that allocations are done in +a linear fashion. All allocations which follow the allocation +passed to gc_keep() are treated as children. This can lead to +small memory leaks, but it seems to work ok in practice. -Memory can be reclaimed by invoking gc(). This -has the following function prototype: +Memory can be reclaimed by invoking gc(). This has the following +function prototype: gc() -The gc() function normally shouldn't need to be -called directly. It's invoked by the allocator -when one of the collection lists fills up, or -when memory allocation fails. +The gc() function normally shouldn't need to be called +directly. It's invoked by the allocator when one of the +collection lists fills up, or when memory allocation fails. -When gc() is invoked, it will remove the oldest -allocations on each list. Up to 64 GC_TEMP -allocations and 32 GC_MEM allocations will be -freed per invokation. +When gc() is invoked, it will remove the oldest allocations on +each list. Up to 64 GC_TEMP allocations and 32 GC_MEM +allocations will be freed per invokation. -If there are less than 64 GC_TEMP or 32 GC_MEM -items, the corresponding lists will be left -alone. +If there are less than 64 GC_TEMP or 32 GC_MEM items, the +corresponding lists will be left alone. -Note that you can potentially lose valid -allocations if you manually invoke gc() when -there are just slightly more than 32 GC_MEM -allocations. +Note that you can potentially lose valid allocations if you +manually invoke gc() when there are just slightly more than 32 +GC_MEM allocations. doc/gc.txt ed1d70314acbc911d3ac9f4b33a0f1e956e51c62 Charles Childers crc.platypus@gmail.com http://github.com/crcx/toka/commit/4d9363c9e4b09b6034d2db92e8c82d4c0683c21d 4d9363c9e4b09b6034d2db92e8c82d4c0683c21d 2009-04-08T20:49:52-07:00 2009-04-08T20:49:52-07:00 minor work on the docs 93dbbf2d16255ac1a41cae39d90ed77a08fd9908 Charles Childers crc.platypus@gmail.com