basis/classes/struct/struct-docs.factor

   1 ! Copyright (C) Joe Groff.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: alien classes classes.struct.private help.markup help.syntax
   4 kernel libc math sequences ;
   5 IN: classes.struct
   6
   7 HELP: <struct-boa>
   8 { $values
   9     { "class" class }
  10 }
  11 { $description "This macro implements " { $link boa } " for " { $link struct } " classes. A struct of the given class is constructed, and its slots are initialized using values off the top of the datastack." } ;
  12
  13 HELP: (struct)
  14 { $values
  15     { "class" class }
  16     { "struct" struct }
  17 }
  18 { $description "Allocates garbage-collected heap memory for a new " { $link struct } " of the specified " { $snippet "class" } ". The new struct's slots are left uninitialized; in most cases, the " { $link <struct> } " word, which initializes the struct's slots with their initial values, should be used instead." } ;
  19
  20 { (struct) (malloc-struct) } related-words
  21
  22 HELP: <struct>
  23 { $values
  24     { "class" class }
  25     { "struct" struct }
  26 }
  27 { $description "Allocates garbage-collected heap memory for a new " { $link struct } " of the specified " { $snippet "class" } ". The new struct's slots are initialized with the initial values specified in the struct definition." } ;
  28
  29 { <struct> <struct-boa> malloc-struct memory>struct } related-words
  30
  31 HELP: STRUCT:
  32 { $syntax "STRUCT: class { slot type } { slot type } ... ;" }
  33 { $values { "class" "a new " { $link struct } " class to define" } { "slots" "a list of slot specifiers" } }
  34 { $description "Defines a new " { $link struct } " type. The syntax is nearly identical to " { $link POSTPONE: TUPLE: } "; however, there are some additional restrictions on struct types:"
  35 { $list
  36 { "Struct classes cannot have a superclass defined." }
  37 { "The slots of a struct must all have a type declared. The type must be a C type." }
  38 { { $link read-only } " slots on structs are not enforced, though they may be declared." }
  39 }
  40 "Additionally, structs may use bit fields. A slot specifier may use the syntax " { $snippet "bits: n" } " to specify that the bit width of the slot is " { $snippet "n" } ". Bit width may be specified on signed or unsigned integer slots. The layout of bit fields is not guaranteed to match that of any particular C compiler." } ;
  41
  42 HELP: S{
  43 { $syntax "S{ class slots... }" }
  44 { $values { "class" "a " { $link struct } " class word" } { "slots" "slot values" } }
  45 { $description "Marks the beginning of a literal struct. The syntax is identical to tuple literal syntax with " { $link POSTPONE: T{ } { $snippet " }" } "; either the assoc syntax (that is, " { $snippet "S{ class { slot value } { slot value } ... }" } ") or the simple syntax (" { $snippet "S{ class f value value ... }" } ") can be used." } ;
  46
  47 HELP: S@
  48 { $syntax "S@ class alien" }
  49 { $values { "class" "a " { $link struct } " class word" } { "alien" "a literal alien" } }
  50 { $description "Marks the beginning of a literal struct at a specific C address. The prettyprinter uses this syntax when the memory backing a struct object is invalid. This syntax should not generally be used in source code." } ;
  51
  52 { POSTPONE: S{ POSTPONE: S@ } related-words
  53
  54 HELP: UNION-STRUCT:
  55 { $syntax "UNION-STRUCT: class { slot type } { slot type } ... ;" }
  56 { $values { "class" "a new " { $link struct } " class to define" } { "slots" "a list of slot specifiers" } }
  57 { $description "Defines a new " { $link struct } " type where all of the slots share the same storage. See " { $link POSTPONE: STRUCT: } " for details on the syntax." } ;
  58
  59 HELP: PACKED-STRUCT:
  60 { $syntax "PACKED-STRUCT: class { slot type } { slot type } ... ;" }
  61 { $values { "class" "a new " { $link struct } " class to define" } { "slots" "a list of slot specifiers" } }
  62 { $description "Defines a new " { $link struct } " type with no alignment padding between slots or at the end. In all other respects, behaves like " { $link POSTPONE: STRUCT: } "." } ;
  63
  64 HELP: define-struct-class
  65 { $values
  66     { "class" class } { "slots" "a sequence of " { $link struct-slot-spec } "s" }
  67 }
  68 { $description "Defines a new " { $link struct } " class. This is the runtime equivalent of the " { $link POSTPONE: STRUCT: } " syntax." } ;
  69
  70 HELP: define-packed-struct-class
  71 { $values
  72     { "class" class } { "slots" "a sequence of " { $link struct-slot-spec } "s" }
  73 }
  74 { $description "Defines a new " { $link struct } " class. This is the runtime equivalent of the " { $link POSTPONE: PACKED-STRUCT: } " syntax." } ;
  75
  76 HELP: define-union-struct-class
  77 { $values
  78     { "class" class } { "slots" "a sequence of " { $link struct-slot-spec } "s" }
  79 }
  80 { $description "Defines a new " { $link struct } " class where all of the slots share the same storage. This is the runtime equivalent of the " { $link POSTPONE: UNION-STRUCT: } " syntax." } ;
  81
  82 HELP: malloc-struct
  83 { $values
  84     { "class" class }
  85     { "struct" struct }
  86 }
  87 { $description "Allocates unmanaged C heap memory for a new " { $link struct } " of the specified " { $snippet "class" } ". The new struct's slots are initialized to their initial values. The struct should be " { $link free } "d when it is no longer needed." } ;
  88
  89 HELP: (malloc-struct)
  90 { $values
  91     { "class" class }
  92     { "struct" struct }
  93 }
  94 { $description "Allocates unmanaged C heap memory for a new " { $link struct } " of the specified " { $snippet "class" } ". The new struct's slots are left uninitialized; to initialize the allocated memory with the slots' initial values, use " { $link malloc-struct } ". The struct should be " { $link free } "d when it is no longer needed." } ;
  95
  96 HELP: compute-struct-offsets
  97 { $values { "slots" sequence } { "size" integer } }
  98 { $description "Computes how many bytes of memory the struct takes, minus final padding." } ;
  99
 100 HELP: memory>struct
 101 { $values
 102     { "ptr" c-ptr } { "class" class }
 103     { "struct" struct }
 104 }
 105 { $description "Constructs a new " { $link struct } " of the specified " { $snippet "class" } " at the memory location referenced by " { $snippet "ptr" } ". The referenced memory is unchanged." } ;
 106
 107 HELP: read-struct
 108 { $values { "class" class } { "struct" struct } }
 109 { $description "Reads a new " { $link struct } " of the specified " { $snippet "class" } "." } ;
 110
 111 HELP: struct
 112 { $class-description "The parent class of all struct types." } ;
 113
 114 { struct POSTPONE: STRUCT: POSTPONE: UNION-STRUCT: } related-words
 115
 116 HELP: struct-class
 117 { $class-description "The metaclass of all " { $link struct } " classes." } ;
 118
 119 HELP: struct-slot-values
 120 { $values { "struct" struct } { "sequence" sequence } }
 121 { $description "Extracts the values of the structs slots" }
 122 { $errors "Throws a memory protection error if the memory the struct references is not accessible." } ;
 123
 124 ARTICLE: "classes.struct.examples" "Struct class examples"
 125 "A struct with a variety of fields:"
 126 { $code
 127     "USING: alien.c-types classes.struct ;"
 128     ""
 129     "STRUCT: test-struct"
 130     "    { i int }"
 131     "    { chicken char[16] }"
 132     "    { data void* } ;"
 133 }
 134 "Creating a new instance of this struct, and printing out:"
 135 { $code "test-struct <struct> ." }
 136 "Creating a new instance with slots initialized from the stack:"
 137 { $code
 138     "USING: libc specialized-arrays alien.data ;"
 139     "SPECIALIZED-ARRAY: char"
 140     ""
 141     "42"
 142     "\"Hello, chicken.\" char >c-array"
 143     "1024 malloc"
 144     "test-struct <struct-boa> ."
 145 } ;
 146
 147 ARTICLE: "classes.struct.define" "Defining struct classes"
 148 "Struct classes are defined using a syntax similar to the " { $link POSTPONE: TUPLE: } " syntax for defining tuple classes:"
 149 { $subsections POSTPONE: STRUCT: POSTPONE: PACKED-STRUCT: }
 150 "Union structs are also supported, which behave like structs but share the same memory for all the slots."
 151 { $subsections POSTPONE: UNION-STRUCT: } ;
 152
 153 ARTICLE: "classes.struct.create" "Creating instances of structs"
 154 "Structs can be allocated with " { $link new } "- and " { $link boa } "-like constructor words. Additional words are provided for building structs from C memory and from existing buffers:"
 155 { $subsections
 156     <struct>
 157     <struct-boa>
 158     malloc-struct
 159     memory>struct
 160 }
 161 "When the contents of a struct will be immediately reset, faster primitive words are available that will create a struct without initializing its contents:"
 162 { $subsections
 163     (struct)
 164     (malloc-struct)
 165 }
 166 "Structs have literal syntax, similar to " { $link POSTPONE: T{ } " for tuples:"
 167 { $subsections POSTPONE: S{ } ;
 168
 169 ARTICLE: "classes.struct.c" "Passing structs to C functions"
 170 "Structs can be passed and returned by value, or by reference."
 171 $nl
 172 "If a parameter is declared with a struct type, the parameter is passed by value. To pass a struct by reference, declare a parameter with a pointer to struct type."
 173 $nl
 174 { $heading "C functions returning structs" }
 175 "If a C function is declared as returning a struct type, the struct is returned by value, and wrapped in an instance of the correct struct class automatically. If a C function is declared as returning a pointer to a struct, it will return an " { $link alien } " instance. This is because there is no way to distinguish between a pointer to a single struct and a pointer to an array of zero or more structs. It is up to the caller to wrap it in a struct using " { $link memory>struct } ", or a specialized array of structs using " { $snippet "<direct-T-array>" } ", respectively."
 176 $nl
 177 "An example of a struct declaration:"
 178 { $code
 179     "USING: alien.c-types classes.struct ;"
 180     ""
 181     "STRUCT: Point"
 182     "    { x int }"
 183     "    { y int }"
 184     "    { z int } ;"
 185 }
 186 "A C function which returns a struct by value:"
 187 { $code
 188     "USING: alien.syntax ;"
 189     "FUNCTION: Point give_me_a_point ( c-string description )"
 190 }
 191 "A C function which takes a struct parameter by reference:"
 192 { $code
 193     "FUNCTION: void print_point ( Point* p )"
 194 } ;
 195
 196 ARTICLE: "classes.struct" "Struct classes"
 197 "The " { $vocab-link "classes.struct" } " vocabulary implements " { $link struct } " classes. They are similar to " { $link tuple } " classes, but their slots exhibit value semantics, and they are backed by a contiguous structured block of memory. Structs can be used for space-efficient storage of data in the Factor heap, as well as for passing data to and from C libraries using the " { $link "alien" } "."
 198 { $subsections
 199     "classes.struct.examples"
 200     "classes.struct.define"
 201     "classes.struct.create"
 202     "classes.struct.c"
 203 } ;
 204
 205 ABOUT: "classes.struct"