The Sol Programming Language!
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

  1. API Conventions
  2. ===============
  3. This document is intended to be a quick rundown on the necessary information to
  4. start extending and modifying Sol in its source form.
  5. Reference Counting
  6. ------------------
  7. Objects in Sol are *reference-counted* for memory management--that is, when
  8. initially allocated (in `sol_alloc_object`), they are set to a reference count
  9. (see the refcnt member) of 1. Every call to `sol_obj_free` will decrement the
  10. reference count of that object, and, when that reference count reaches zero,
  11. the memory is freed (on the assumption that no other references to that object
  12. exist). This does *not* prevent the occurrence of cycles, and Sol has no
  13. protection against this at the moment.
  14. As a general rule, *all* functions that return object pointers return a *new
  15. reference*--the *caller* is expected to `sol_obj_free` that reference when it
  16. is no longer needed (including immediately, for example). It is also the rule
  17. that functions that take object pointers will *borrow* those references as
  18. needed; for example, data structures that store objects will hold a reference.
  19. Sol State
  20. ---------
  21. The Sol state (type `sol_state_t`) is a structure that is passed to nearly all
  22. functions in the API, and is responsible for managing all the global state of
  23. the interpreter. Due to this separation, Sol is fully reentrant. Designers
  24. looking to modify Sol in a way that requires the introduction of data across
  25. scopes and call frames may add fields to the state; extenders may use or refer
  26. to the state uniquely to determine context, or use objects stored within that
  27. state to accomplish that task.
  28. Naming
  29. ------
  30. Names exported in `sol.h` should be safe to use publicly--that is, they should
  31. have a low chance of conflicting with names used in other programs; the typical
  32. convention is to prefix every such name with "sol_". Names in `ast.h` are not so
  33. restricted, and are typically included in many of the internal C files. `ast.h`
  34. includes `sol.h`, and so only one of the two headers needs to be used. Note that
  35. some references in structures defined in `sol.h` refer to types in `ast.h`, and
  36. these are intentionally left as void pointers; Comments and other documentation
  37. should indicate their true type.
  38. File Structure
  39. --------------
  40. This list represents the file structure at this time, and may not be kept up to
  41. date:
  42. - object.c contains all routines for the runtime, including creation,
  43. destruction, and manipulation of most objects.
  44. - builtins.c contains the vast majority of built-in functionality, including
  45. most of the type methods as included in the `sol_ops_t` structures.
  46. - runtime.c contains the interpreter and related routines, including execution
  47. and evaluation, ones defining the calling convention, and the manipulation of
  48. ASTs.
  49. - state.c contains state management routines, such as those for initializing
  50. and finalizing a state, getting or setting errors, and resolving names in
  51. scopes. Module, type method, and other initialization is done here.
  52. - gc.c contains the memory management routines.
  53. - astprint.c contains routines for displaying ASTs on stdout.
  54. - solrun.c contains the main() function for the interpreter.
  55. - cdata.c contains definitions of various CDATA (C interface) types--presently,
  56. only the CStruct (a way for C code to specify struct layouts to Sol
  57. programs).
  58. - util.c contains utility routines--importantly, a safe call/return trampoline
  59. for extension code.