Browse Source

Sol Part 44: The Words I Don't Know Could Fill A Dictionary!

Graham Northup 5 years ago
parent
commit
edae755438
4 changed files with 158 additions and 0 deletions
  1. 70
    0
      doc/src/api_conventions.rst
  2. 1
    0
      doc/src/index.rst
  3. 55
    0
      gc.c
  4. 32
    0
      sol.h

+ 70
- 0
doc/src/api_conventions.rst View File

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

+ 1
- 0
doc/src/index.rst View File

@@ -11,5 +11,6 @@ the documentation on "doxygenfile".
11 11
 
12 12
 .. toctree::
13 13
     
14
+    api_conventions
14 15
     sol_h
15 16
     ast_h

+ 55
- 0
gc.c View File

@@ -3,6 +3,11 @@
3 3
 #include <time.h>
4 4
 #include "sol.h"
5 5
 
6
+/** Allocates and returns a new reference to a typeless object.
7
+ *
8
+ * This is an internal function. Users should use `sol_alloc_object` instead.
9
+ */
10
+
6 11
 sol_object_t *_sol_gc_alloc_object(sol_state_t *state) {
7 12
 	sol_object_t *res = malloc(sizeof(sol_object_t));
8 13
 	if(!res) {
@@ -14,6 +19,11 @@ sol_object_t *_sol_gc_alloc_object(sol_state_t *state) {
14 19
 	return sol_incref(res);
15 20
 }
16 21
 
22
+/** Frees a reference to an object.
23
+ *
24
+ * This is an internal function. Users should use `sol_obj_free` instead.
25
+ */
26
+
17 27
 void _sol_gc_obj_free(sol_object_t *obj) {
18 28
 	if(!obj) {
19 29
 		printf("WARNING: Attempt to free NULL\n");
@@ -28,6 +38,17 @@ void _sol_gc_obj_free(sol_object_t *obj) {
28 38
 	}
29 39
 }
30 40
 
41
+/** Increments the reference count of an object, and return it.
42
+ *
43
+ * This function is exactly an identity function, but it increments the
44
+ * object's reference count.
45
+ *
46
+ * It is intended for use in places where a function is required, such as
47
+ * assigning to a function pointer.
48
+ *
49
+ * Users with the ability to should use `sol_incref` instead.
50
+ */
51
+
31 52
 sol_object_t *sol_obj_acquire(sol_object_t *obj) {
32 53
 	return sol_incref(obj);
33 54
 }
@@ -107,14 +128,36 @@ void _sol_gc_dsl_destructor(sol_object_t *obj) {
107 128
 
108 129
 #else
109 130
 
131
+/** Allocates and returns a new reference to a typeless object.
132
+ *
133
+ * This function is intended to be called from object constructors that will
134
+ * ultimately set the type and operations on the object.
135
+ *
136
+ * The returned reference is initially the only reference to this object.
137
+ */
138
+
110 139
 sol_object_t *sol_alloc_object(sol_state_t *state) {
111 140
 	return _sol_gc_alloc_object(state);
112 141
 }
113 142
 
143
+/** Frees a reference to an object.
144
+ *
145
+ * If the given reference is the last reference to this object, the memory is
146
+ * freed, after any type-specific destructors are called.
147
+ */
148
+
114 149
 void sol_obj_free(sol_object_t *obj) {
115 150
 	_sol_gc_obj_free(obj);
116 151
 }
117 152
 
153
+/** Destroys an object.
154
+ *
155
+ * This function is called on an object whose last reference has been freed; it
156
+ * is responsible for implementing the destructor protocol (and so calling the
157
+ * necessary methods). In general, it should not be used by user code, as it
158
+ * may introduce use-after-free.
159
+ */
160
+
118 161
 void sol_obj_release(sol_object_t *obj) {
119 162
 	if(obj->ops->free) {
120 163
 		obj->ops->free(NULL, obj);
@@ -122,7 +165,19 @@ void sol_obj_release(sol_object_t *obj) {
122 165
 	free(obj);
123 166
 }
124 167
 
168
+/** Initialize the memory manager for a state.
169
+ *
170
+ * You normally do not need to call this; it is also done in `sol_state_init`.
171
+ */
172
+
125 173
 void sol_mm_initialize(sol_state_t *state) {}
174
+
175
+/** Finalize the memory manager for a state.
176
+ *
177
+ * You normally do not need to call this; it is also done in
178
+ * `sol_state_cleanup`.
179
+ */
180
+
126 181
 void sol_mm_finalize(sol_state_t *state) {}
127 182
 
128 183
 #endif

+ 32
- 0
sol.h View File

@@ -9,14 +9,26 @@
9 9
 #include <stdarg.h>
10 10
 #include "dsl/dsl.h"
11 11
 
12
+/** The version of the project, as made available through `debug.version`. */
12 13
 #define VERSION "0.2a0"
14
+/** The hexadecimal version of the project, formatted 0xAAIIRPP where:
15
+ * 
16
+ * - AA is the two-digit major version
17
+ * - II is the two-digit minor version
18
+ * - R is 'A' for alpha, 'B' for beta, 'C' for candidate, and 'F' for final
19
+ * - PP is the two-digit patch
20
+ *
21
+ * This value is guaranteed to always increase by revision.
22
+ */
13 23
 #define HEXVER 0x0002A00
14 24
 
15 25
 #ifndef SOL_ICACHE_MIN
26
+/** The smallest integer to cache. */
16 27
 #define SOL_ICACHE_MIN -128
17 28
 #endif
18 29
 
19 30
 #ifndef SOL_ICACHE_MAX
31
+/** The largest integer to cache. */
20 32
 #define SOL_ICACHE_MAX 256
21 33
 #endif
22 34
 
@@ -31,8 +43,28 @@ typedef struct sol_tag_object_t sol_object_t;
31 43
 struct sol_tag_state_t;
32 44
 typedef struct sol_tag_state_t sol_state_t;
33 45
 
46
+/** CFunction type.
47
+ *
48
+ * This is the essential type for most C interface routines. It receives two
49
+ * parameters:
50
+ *
51
+ * - The state under which the function is invoked, and
52
+ * - A list object containing a set of parameters, which are generally
53
+ *   well-defined per location or operation.
54
+ *
55
+ * The function should return a new reference to an object. If the value is
56
+ * unimportant or otherwise ignored, the canonical return value is
57
+ * `sol_incref`(state->None).
58
+ */
59
+
34 60
 typedef sol_object_t *(*sol_cfunc_t)(sol_state_t *, sol_object_t *);
35 61
 
62
+/** Print function type.
63
+ *
64
+ * \deprecated This is not used anywhere and is likely to be removed in the
65
+ * near future.
66
+ */
67
+
36 68
 typedef void (*sol_printfunc_t)(sol_object_t *);
37 69
 
38 70
 typedef struct {

Loading…
Cancel
Save