Guile Binary Format 0.0

[Keisuke Nishida]

Hello,

I have commited my initial version of a binary loader.  Currently,
it supports all immediates, conses, symbols, strings, and keywords.

Scheme Interface
----------------

- Procedure: binary-write OBJ [PORT]

Write OBJ into PORT or the current output port in the binary format.

- Procedure: binary-read [PORT]

Read an object from PORT or the current input port in the binary format.

[ Currently, only one object can be written/readed ]

C Interface
-----------

- Function: scm_set_smob_dump (tc, mark, dealloc, store)
- Function: scm_set_smob_undump (tc, alloc, restore, init)

Set smob's dump/undump functions.

`mark' is a function that tells what objects should be saved in relation
to this smob.  `dealloc' is a function that saves smob data.  `store' is
a function that stores related objects marked by `mark'.

`alloc' is a function that allocates a smob, loading the data saved in
`dealloc'.  `restore' is a function that restores objects stored in
`store'.  `init' is a function that is called after undump is done.

- Function: scm_dump_mark (obj, dstate)

Mark an object for dumping.

- Function: scm_store_string (addr, size, dstate)
- Function: scm_store_bytes (addr, size, dstate)
- Function: scm_store_word (word, dstate)
- Function: scm_store_object (obj, dstate)

Functions that store smob data and related objects.

- Function: scm_restore_string (dstate, lenp)
- Function: scm_restore_bytes (dstate, size)
- Function: scm_restore_word (dstate)
- Function: scm_restore_object (state)

Functions that restore smob data and related objects.

Smob Example
------------

scm_bits_t smob_foo;

struct foo {
  int x, y;
  SCM bar, baz;
}

#define FOO_DATA(x)  ((struct foo *) SCM_SMOB_DATA (x))

SCM
foo_dump_mark (SCM obj, SCM dstate)
{
  scm_dump_mark (FOO_DATA (obj)->bar, dstate);
  return FOO_DATA (obj)->baz;
}

void
foo_dump_dealloc (SCM obj, SCM dstate)
{
  scm_store_word (FOO_DATA (obj)->x, dstate);
  scm_store_word (FOO_DATA (obj)->y, dstate);
}

void
foo_dump_store (SCM obj, SCM dstate)
{
  scm_store_object (FOO_DATA (obj)->bar, dstate);
  scm_store_object (FOO_DATA (obj)->baz, dstate);
}

SCM
foo_undump_alloc (SCM dstate)
{
  struct foo *p = scm_must_malloc (sizeof (struct foo), "foo_undump_alloc");
  p->x   = scm_restore_word (dstate);
  p->y   = scm_restore_word (dstate);
  p->bar = SCM_BOOL_F;
  p->baz = SCM_BOOL_F;
  SCM_RETURN_NEWSMOB (smob_foo, p);
}

void
foo_undump_restore (SCM obj, SCM dstate)
{
  FOO_DATA (obj)->bar = scm_restore_object (dstate);
  FOO_DATA (obj)->baz = scm_restore_object (dstate);
}

void
init_foo ()
{
  smob_foo = scm_make_smob_type ("foo", 0);
  scm_set_smob_dump (smob_foo, foo_dump_mark, foo_dump_dealloc, foo_dump_store);
  scm_set_smob_undump (smob_foo, foo_undump_alloc, foo_undump_restore, 0);
}

Why So Complex?
---------------

Objects stored might have circular references.  During undumping,
when `alloc' is called, there is no guarantee that all necessary
objects have already been loaded.  This implies that we first need
to allocate smobs, and then initialize them.

`restore` is called when all objects are on memory, so we are ready
to link them with each other.  However, there is no guarantee that
they are already initialized.  `init' is called after restoration
process, but the same problem is there, so maybe this is redundant..

The reason why there are three dumping functions is probably because
I'm too lazy..  I guess I can unify them into one or two functions
some time later.

Binary Format
-------------

1. Header section - Cookie, format version, etc.
2. Meta section   - Meta information of stored objects
3. Data section   - Object data

o Header section

[32 bits]  Cookie string  = "\?GBF"
[32 bits]  Version string = "-0.0"
[32 bits]  The number of meta data
[32 bits]  Initial object indicator (see below)

o Meta section

This section contains a sequence of meta data.  A meta datum consists of
the following data:

[32 bits]  Type specifier
[32 bits]  The number of objects of that type

A type specifier has the same value as one of Gulie's scm_tc* tags.

o Deta section

This section contains binary data used for building objects.

o Object indicator

An object indicator is a 32-bit datum that indicates an object stored in
a binary file.  For immediate objects, its representation is used as its
indicator.  Non-immediate objects are stored in a local object table and
indicated by its index value.  An index value is encoded by "index << 3"
so as to avoid conflict with immediate values.

When a binary file is loaded, the object indicated by the initial object
indicator is returned.

[ To be written more ]


I'll have some experiments with this and improve it.

Kei