Index: TODO =================================================================== diff -u -r7de98927e7132b1c6dac8c0702b16189fe9bdf03 -rda13fea984860450c9b2221a08864947dbc0334c --- TODO (.../TODO) (revision 7de98927e7132b1c6dac8c0702b16189fe9bdf03) +++ TODO (.../TODO) (revision da13fea984860450c9b2221a08864947dbc0334c) @@ -4926,6 +4926,10 @@ ======================================================================== TODO: +- Why do we still have a method volatile in nx? Why not leave it as + configure/cget configuration option only?! At least, I cannot recall the + rationale behind keeping the method anymore :/ + - remove / rephrase "//"-comments - ParamGetDomain(Nsf_Param CONST *paramPtr) does not work for enumeration types defined in derived packages, having Index: doc/Object.man =================================================================== diff -u -re6cf818551149b3ff669a69e97de1ea56f124e18 -rda13fea984860450c9b2221a08864947dbc0334c --- doc/Object.man (.../Object.man) (revision e6cf818551149b3ff669a69e97de1ea56f124e18) +++ doc/Object.man (.../Object.man) (revision da13fea984860450c9b2221a08864947dbc0334c) @@ -3,6 +3,7 @@ [keywords baseclass] [keywords NX] +[keywords "mixin class"] [copyright {2014 Stefan Sobernig , Gustaf Neumann }] [titledesc {nx::Object API Reference}] @@ -57,29 +58,36 @@ [section {Configuration Options for Instances of nx::Object}] -[para] -Configuration options can be used for the configuration during object -creation via non-positional arguments for [method new] and [method create], -they can be altered via [method configure], or queried via [method cget]. +[para] Configuration options can be used for configuring objects during +their creation by passing the options as non-positional arguments into calls +of [method new] and [method create] (see [cmd nx::Class]). An +existing object can be queried for its current configuration using +[method cget] and it can be re-configured using [method configure]. [list_begin options] [opt_def -class [arg className]] -Class of the object. +Returns the current class of the object or re-classes the object to [arg className], if provided. [opt_def -object-filter [arg filterMethods]] -List of per-object filter methods. +Returns the list of currently active per-object filter methods or sets +a list of per-object filter methods, if [arg filterMethods] is +provided. -[opt_def -object-mixin [arg mixinSpec]] +[opt_def -object-mixin [arg mixinSpecs]] -List of mixinSpecs. A [arg mixinSpec] is of the form of ... +Returns the list of currently active per-object mixin specifications +or sets a list of per-object mixin specifications to become +active. [arg mixinSpecs] is of the form of ... [opt_def -volatile] -Volatile state. Volatile objects are destroyed automatically upon -leaving the variable scope where volatile was set. +A volatile object is automatically destroyed (see [method destroy]) +when, during program execution, the variable scope, in which [option -volatile] was +configured for a given object for the first time (e.g., the call frame +of a proc), is cleaned up. [list_end] @@ -214,11 +222,25 @@ [method destroy] will trigger the actual, physical object destruction via [cmd next]. +[example { +% [nx::Object create obj { + :public method destroy {} { + puts "destroying [self]" + next; # physical destruction + } +}] destroy +destroying ::obj +}] + +A customized object-desctruction scheme can be made shared between the instances +of a class, by defining the custom [method destroy] for an +application class: + [example_begin] % nx::Class create Foo { :method destroy {} { - puts "destroying [lb]self[rb]" - next + puts "destroying [lb]self[rb]" + next; # physical destruction } } ::Foo @@ -228,21 +250,28 @@ destroying ::f1 [example_end] -Some background details: The method <<@class.method "::nx::Object destroy">> -delegates the actual destruction to <<@class.method "::nx::Class -dealloc">> which clears the memory object storage. Essentially, this -behavior could be scripted as: +Physical destruction is performed by clearing the in-memory object +storage of [arg obj]. This is achieved by passing [arg obj] into a +call to [method dealloc] provided by [cmd nx::Class]. A near, scripted +equivalent to the C-implemented [method destroy] provided by [cmd nx::Object] would look +as follows: [example { -Object method destroy {} { +% Object method destroy {} { [:info class] dealloc [self] } }] -Note, however, that '''destroy''' is protected against -application-level redefinition. You must refine it in a subclass -or a <<@gls mixin_class>>. +Note, however, that [method destroy] is protected against +application-level redefinition. Trying to evaluate the above script snippet yields: +[example { +refuse to overwrite protected method 'destroy'; derive e.g. a sub-class! +}] + +A custom [method destroy] must be provided as a refinement in a +subclass of [cmd nx::Object] or in a [term "mixin class"]. + [list_end] [cmd_def eval]