You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
70 lines
3.4 KiB
70 lines
3.4 KiB
API Conventions
|
|
===============
|
|
|
|
This document is intended to be a quick rundown on the necessary information to
|
|
start extending and modifying Sol in its source form.
|
|
|
|
Reference Counting
|
|
------------------
|
|
|
|
Objects in Sol are *reference-counted* for memory management--that is, when
|
|
initially allocated (in `sol_alloc_object`), they are set to a reference count
|
|
(see the refcnt member) of 1. Every call to `sol_obj_free` will decrement the
|
|
reference count of that object, and, when that reference count reaches zero,
|
|
the memory is freed (on the assumption that no other references to that object
|
|
exist). This does *not* prevent the occurrence of cycles, and Sol has no
|
|
protection against this at the moment.
|
|
|
|
As a general rule, *all* functions that return object pointers return a *new
|
|
reference*--the *caller* is expected to `sol_obj_free` that reference when it
|
|
is no longer needed (including immediately, for example). It is also the rule
|
|
that functions that take object pointers will *borrow* those references as
|
|
needed; for example, data structures that store objects will hold a reference.
|
|
|
|
Sol State
|
|
---------
|
|
|
|
The Sol state (type `sol_state_t`) is a structure that is passed to nearly all
|
|
functions in the API, and is responsible for managing all the global state of
|
|
the interpreter. Due to this separation, Sol is fully reentrant. Designers
|
|
looking to modify Sol in a way that requires the introduction of data across
|
|
scopes and call frames may add fields to the state; extenders may use or refer
|
|
to the state uniquely to determine context, or use objects stored within that
|
|
state to accomplish that task.
|
|
|
|
Naming
|
|
------
|
|
|
|
Names exported in `sol.h` should be safe to use publicly--that is, they should
|
|
have a low chance of conflicting with names used in other programs; the typical
|
|
convention is to prefix every such name with "sol_". Names in `ast.h` are not so
|
|
restricted, and are typically included in many of the internal C files. `ast.h`
|
|
includes `sol.h`, and so only one of the two headers needs to be used. Note that
|
|
some references in structures defined in `sol.h` refer to types in `ast.h`, and
|
|
these are intentionally left as void pointers; Comments and other documentation
|
|
should indicate their true type.
|
|
|
|
File Structure
|
|
--------------
|
|
|
|
This list represents the file structure at this time, and may not be kept up to
|
|
date:
|
|
|
|
- object.c contains all routines for the runtime, including creation,
|
|
destruction, and manipulation of most objects.
|
|
- builtins.c contains the vast majority of built-in functionality, including
|
|
most of the type methods as included in the `sol_ops_t` structures.
|
|
- runtime.c contains the interpreter and related routines, including execution
|
|
and evaluation, ones defining the calling convention, and the manipulation of
|
|
ASTs.
|
|
- state.c contains state management routines, such as those for initializing
|
|
and finalizing a state, getting or setting errors, and resolving names in
|
|
scopes. Module, type method, and other initialization is done here.
|
|
- gc.c contains the memory management routines.
|
|
- astprint.c contains routines for displaying ASTs on stdout.
|
|
- solrun.c contains the main() function for the interpreter.
|
|
- cdata.c contains definitions of various CDATA (C interface) types--presently,
|
|
only the CStruct (a way for C code to specify struct layouts to Sol
|
|
programs).
|
|
- util.c contains utility routines--importantly, a safe call/return trampoline
|
|
for extension code.
|