BUFFER:

`BUFFER:`

[ RfDs/CfVs | Other proposals ]

Poll Standings

See below for voting instructions.

Systems

[ ] conforms to ANS Forth.: SwiftForth
SwiftX
[ ] already implements the proposal in full since release [ ].: 4tH [3.5d]
SwiftForth [3.0]
SwiftX [3.0]
OpenFirmware
CForth93
VFX Forth
Forth 6
Forth 7
[ ] implements the proposal in full in a development version.: VFX Forth [10 to 15 years]
Forth 6 [10 to 15 years]
Forth 7 [10 to 15 years]
[ ] will implement the proposal in full in release [ ].
[ ] will implement the proposal in full in some future release.
[ ] There are no plans to implement the proposal in full in [ ].
[ ] will never implement the proposal in full.

Programmers

[ ] I have used (parts of) this proposal in my programs.: Hans Bezemer
Leon Wagner
Brad Eckert
Stephen Pelc
[ ] I would use (parts of) this proposal in my programs if the systems I am interested in implemented it.: Bruce R. McFarling
David Kuehling
Brad Eckert
Gerry Jackson
Stephen Pelc
[ ] I would use (parts of) this proposal in my programs if this proposal was in the Forth standard.: Bruce R. McFarling
Brad Eckert
Gerry Jackson
[ ] I would not use (parts of) this proposal in my programs.

Informal Results

David Kuehling
I feel that the BUFFER: proposal has a number of flaws:
- It does merely solve problems that are outside the scope of the standard: memory segmentation during (cross)-compilation of programs/turn-key systems; problems with direct threaded code on harvard-cache CPUs.
- it defines high-level functionality where corresponding lower-level functionality would provide the same or more features. If there is a magical dictionary of data initialized "later" (meaning of "later" cannot properly be defined within the standard!?), give me access to that dictionary using UHERE and UALLOT (or UALLOCATE or whatever), instead of providing a higher-level defining word.
Stephen Pelc
In the reference implementation, the phrase "carnal knowledge" should be replaced with the phrase "implementation-specific knowledge ".

Peter Knaggs
The test cases should be removed as the make the assumption that the uninitialised memory space is in the dictionary. I suggest the following test cases be used in their place.

DECIMAL
T{ 255 BUFFER: TBUF1 -> }T
T{ 100 BUFFER: TBUF2 -> }T

T{ TBUF2 TBUF1 - ABS 255 > -> <TRUE> }T  \ Buffers do not overlap
T{ TBUF1 ALIGNED -> TBUFF1 }T            \ Buffer is aligned
 
: TERASE? ( addr n1 -- n2 )
  0 SWAP 0 ?DO
    OVER C@ OR SWAP CHAR+ SWAP
  LOOP NIP ;
  
T{ TBUF1 255 ERASE -> }T                 \ Can buffer be written
T{ TBUF1 255 TERASE? -> 0 }T

24 September 2010, Stephen Pelc

Rationale

Problem

Despite the wording in the ANS Forth specification, the majority of Forth systems, either hosted or embedded, use a single memory space in which words such as CREATE, comma and ALLOT refer to the same area of memory. Open Firmware and the draft cross compiler word set provide the word BUFFER: ( u "<spaces>name" -- ) to create a buffer.

This word is provided by several hosted Forths. It is particularly useful on CPUs (including all current x86 PC processors) which require separation of code and data for best performance.

BUFFER: permits implementers to create buffers in any available memory region, not just the dictionary data area.

Current practise

At least SwiftForth, VFX Forth, some versions of Win32Forth, Open Firmware and the draft cross compiler word set provide BUFFER: already.

An optimal version of BUFFER: cannot be written without carnal knowledge of the underlying Forth system.

By introducing BUFFER: a system can preserve the behaviour of CREATE, comma, ALLOT and friends as referring to a common data space preserving common entitlements such as

CREATE FOOP 55 , 66 , 100 ALLOT

while providing BUFFER: for highest performance and increasing compatibility with embedded systems code.

Approach

At very least the use of

256 BUFFER: Xbuff

is more readable than

CREATE Xbuff 256 ALLOT

The proposal below provides a more consistent approach than code such as

CREATE Xbuff 0 C, 255 ALLOT

which is replaced by

256 BUFFER: Xbuff 0 Xbuff C!

Note that in systems with separated code and data space, the occasionally seen phrase

VARIABLE Xbuff 256 CELL - ALLOT

may not give correct results, whereas the approach above will work.

Proposal

6.2.aaaa BUFFER:                                buffer-colon CORE EXT

( u "<spaces>name" -- ): Skip leading space delimiters. Parse name delimited by a space. Create a definition for name, with the execution semantics defined below. Reserve u address units at an aligned address. Contiguity of this region with any other region is undefined.
name Execution: ( -- a-addr ): A-addr is the address of the space reserved by BUFFER: when it defined name. The program is responsible for initialising the contents.

Reference Implementation

This implementation depends on children of CREATE returning an aligned address as already specified by Forth200x. Other memory location techniques require implementation-specific knowledge of the underlying Forth system.


: BUFFER:     \ u "<name>" -- ; -- addr
\ Create a buffer of u address units whose address is returned
\ at run time.
  CREATE ALLOT
;

Test Cases


DECIMAL
T{ 10 BUFFER: TBUF -> }T
T{ HERE 10 - -> TBUF }T

Change History

2010-09-24: Change characters to address units.
Rewrote rationale.
Removed contiguity paragraph.
2010-04-02: Changed n to u.
2010-03-30: Spolling chekks.

Credits

Stephen Pelc, <stephen@mpeforth.com>
MicroProcessor Engineering Ltd - More Real, Less Time
133 Hill Lane, Southampton SO15 5AF, England
tel: +44 (0)23 8063 1441,
fax: +44 (0)23 8033 9691
web: www.mpeforth.com - free VFX Forth downloads

Voting Instructions

Fill out the appropriate ballot(s) below and mail it/them to <vote@forth200x.org>. Your vote will be published (including your name (without email address) and/or the name of your system) here. You can vote (or change your vote) at any time, and the results will be published here.

Note that you can be both a system implementor and a programmer, so you can submit both kinds of ballots.

Ballot for systems

If you maintain several systems, please mention the systems separately in the ballot. Insert the system name or version between the brackets. Multiple hits for the same system are possible (if they do not conflict).

[ ] conforms to ANS Forth.
[ ] already implements the proposal in full since release [ ].
[ ] implements the proposal in full in a development version.
[ ] will implement the proposal in full in release [ ].
[ ] will implement the proposal in full in some future release.
[ ] There are no plans to implement the proposal in full in [ ].
[ ] will never implement the proposal in full.

If you want to provide information on partial implementation, please do so informally, and I will aggregate this information in some way.

Ballot for programmers

Just mark the statements that are correct for you (e.g., by putting an "x" between the brackets). If some statements are true for some of your programs, but not others, please mark the statements for the dominating class of programs you write.

[ ] I have used (parts of) this proposal in my programs.
[ ] I would use (parts of) this proposal in my programs if the systems I am interested in implemented it.
[ ] I would use (parts of) this proposal in my programs if this proposal was in the Forth standard.
[ ] I would not use (parts of) this proposal in my programs.

If you feel that there is closely related functionality missing from the proposal (especially if you have used that in your programs), make an informal comment, and I will collect these, too. Note that the best time to voice such issues is the RfD stage.