x-base.h File Reference

Base environment object – the root context for evaluation. More...

#include "x-obj.h"

Go to the source code of this file.

Data Structures
struct	x_base_t

Macros
#define	x_base_field_io_group(X)   x_firstobj(x_restobj(x_base(X)))
#define	x_base_field_files(X)   x_restobj(x_firstobj(x_base_field_io_group(X)))
#define	x_base_field_filein(X)   x_firstobj(x_base_field_files(X))
#define	x_base_field_fileout(X)   x_firstobj(x_restobj(x_base_field_files(X)))
#define	x_base_field_fileerr(X)   x_firstobj(x_restobj(x_restobj(x_base_field_files(X))))
#define	x_base_field_write_buf(X)   x_firstobj(x_restobj(x_restobj(x_restobj(x_base_field_files(X)))))
#define	x_base_field_buffer(X)   x_firstobj(x_restobj(x_restobj(x_restobj(x_restobj(x_base_field_files(X))))))
#define	x_base_field_meta_group(X)   x_restobj(x_restobj(x_base(X)))
#define	x_base_field_profile(X)   x_firstobj(x_firstobj(x_base_field_meta_group(X)))
#define	x_base_field_profile_allocs(X)   x_firstobj(x_base_field_profile(X))
#define	x_base_field_hooks(X)   x_restobj(x_firstobj(x_base_field_meta_group(X)))
#define	x_base_field_hook_type_name(X)   x_firstobj(x_base_field_hooks(X))
#define	x_base_field_hook_units(X)   x_firstobj(x_restobj(x_base_field_hooks(X)))
#define	x_base_field_hook_length(X)   x_firstobj(x_restobj(x_restobj(x_base_field_hooks(X))))
#define	x_base_field_hook_error(X)   x_firstobj(x_restobj(x_restobj(x_restobj(x_base_field_hooks(X)))))
#define	x_base_field_heap_group(X)   x_firstobj(x_restobj(x_base_field_meta_group(X)))
#define	x_base_field_obj_meta_extra(X)   x_firstobj(x_base_field_heap_group(X))
#define	x_base_field_heap_mark(X)   x_firstobj(x_restobj(x_base_field_heap_group(X)))
#define	x_base_field_heap_free(X)   x_firstobj(x_restobj(x_restobj(x_base_field_heap_group(X))))
#define	x_base_field_heap_mark_hooks(X)   x_firstobj(x_restobj(x_restobj(x_restobj(x_base_field_heap_group(X)))))
#define	x_base_field_heap_free_hooks(X)   x_firstobj(x_restobj(x_restobj(x_restobj(x_restobj(x_base_field_heap_group(X))))))
#define	x_base_field_heap_mark_roots(X)   x_firstobj(x_restobj(x_restobj(x_restobj(x_restobj(x_restobj(x_base_field_heap_group(X)))))))
#define	x_base_field_heap_root_chain(X)   x_firstobj(x_restobj(x_restobj(x_restobj(x_restobj(x_restobj(x_restobj(x_base_field_heap_group(X))))))))
#define	x_base_field_alloc_group(X)   x_firstobj(x_restobj(x_restobj(x_base_field_meta_group(X))))
#define	x_base_field_alloc_count(X)   x_firstobj(x_base_field_alloc_group(X))
#define	x_base_field_alloc_limit(X)   x_firstobj(x_restobj(x_base_field_alloc_group(X)))
#define	x_base_field_alloc_error(X)   x_firstobj(x_restobj(x_restobj(x_base_field_alloc_group(X))))
Base Object Root
#define	x_base(X)   x_firstobj(X)
#define	x_base_isset(B)   ((B) != NULL && x_base((B)) != NULL)

Functions
Base Functions
x_obj_t *	x_base_make (x_obj_t *p_base, struct x_base_t base)
x_obj_t *	x_base_read (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_base_write (x_obj_t *p_base, x_obj_t *p_args)

Detailed Description

Base environment object – the root context for evaluation.

The base object is a nested pair tree that holds I/O descriptors, profiling counters, extensible hook functions, and heap/GC state. Field accessor macros navigate this tree without hard-coding offsets.

Every leaf field is stored as a pair – its field cell: (current-value . saved-values). Fields are initialized with (value . nil). Any field can be used as a stack via x_obj_push() / x_obj_pop() to save and restore values. ("Field cell" always means this slot; a plain "cell" is a cons cell, see x-lisp.h.) To read a field's current value, use x_firstobj(field) then extract the appropriate datum (e.g. x_atomint() for integers). To temporarily override a field (e.g. redirect I/O for a nested scope), push a new value before entering the scope and pop it on exit.

Note

The tree layout below is stable API. Field positions will not change within a major version. Extension points (env+ctrl, type-alist, io-state) are reserved for downstream use.

The tree has three extension points (marked below) where downstream projects can attach additional state: env+ctrl for environment bindings, type-alist for type dispatch tables, and io-state for I/O subsystem extensions. These start as nil.

(lit base-data
  (env+ctrl
    . ((; io
        (type-alist
          . (filein fileout fileerr write-buf buffer))
        . io-state)
      . ((; meta
          (; profile . hooks
            (allocs)
            . (type-name units length error))
          . ((; heap
              (obj-meta-extra mark free
               mark-hooks free-hooks mark-roots root-chain)
              . ())
            . ()))
        . ()))))

Author

Jon Ruttan (jonru.nosp@m.ttan.nosp@m.@gmai.nosp@m.l.co.nosp@m.m)

Copyright

2021 Jon Ruttan @license MIT No Attribution (MIT-0)

    ., .,
    {O,O}
    (   )
     " "

Macro Definition Documentation

x_base

#define x_base

(

X

)

x_firstobj(X)

Get the root data of the base object X.

x_base_isset

#define x_base_isset

(

B

)

((B) != NULL && x_base((B)) != NULL)

Test whether the base object B is initialized and has data.

Function Documentation

x_base_make()

x_obj_t * x_base_make	(	x_obj_t *	p_base,
		struct x_base_t	base
	)

Create a new base environment object.

Create a new base environment object.

Allocates and assembles the nested pair tree that holds all environment state. Every node is allocated with X_OBJ_FLAG_SHARED (via the local pair/atom macros) so the base tree is immune to garbage collection. Each leaf value is wrapped as pair(atom(value), nil) to form a one-element field stack (see x-base.h). Hook values passed as NULL produce (nil . nil) leaves (hook disabled). The tree layout matches the field accessor macros: x_base_field_filein() navigates to the filein leaf, x_base_field_hook_type_name() to the type_name hook, etc.

Parameters

p_base	Existing base for allocation context, or NULL for bootstrap.
base	Initialization parameters (file descriptors, hooks, etc.).

Returns

The newly created base object.

x_base_read()

x_obj_t * x_base_read	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Read data from the base's input file descriptor.

Read data from the base's input file descriptor into an atom.

Uses the filein descriptor from the base environment, or falls back to STDIN_FILENO if the base is not initialized.

Parameters

p_base	Base (execution context).
p_args	Pair list: (destination-atom byte-count).

Returns

The destination atom on success, or NULL on read failure. On failure the byte-count atom is overwritten with the raw x_sys_read() result so the caller can tell end-of-stream (0) from a read error (negative): this layer has no error channel, and conflating the two turned transient read errors into silent input truncation (x-lang#170).

x_base_write()

x_obj_t * x_base_write	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Write data to the base's output file descriptor or write buffer.

Write data from an atom to the base's output or write buffer.

Checks the write_buf field first: if it holds a non-nil pair (pointer . position), data is memcpy'd into the buffer at the current position and the position is advanced. Otherwise, writes to the fileout file descriptor, falling back to STDOUT_FILENO if the base is not initialized.

Parameters

p_base	Base (execution context).
p_args	Pair list: (source-atom byte-count).

Returns

The source atom on success, or NULL on write failure.