2.4 Immutability of Objects

  • 2.4.1 Behavior of Interfaces
  • Most CLIM objects are immutable, that is, at the protocol level none of their components can be modified once the object is created. Examples of immutable objects include all of the members of the region classes, colors and opacities, text styles, and line styles. Since immutable objects by definition never change, functions in the CLIM API can safely capture immutable objects without first copying them. This also allows CLIM to cache immutable objects. Constructor functions that return immutable objects are free to either create and return a new object, or return an already existing object. [annotate]

    [immutable, Concept← A Glossary]

    A few CLIM objects are mutable. Examples of mutable objects include streams and output records. Some components of mutable objects can be modified once the object has been created, usually via setf accessors. [annotate]

    [mutable, Concept← A Glossary]

    In CLIM, object immutability is maintained at the class level. Throughout this specification, the immutability or mutability of a class will be explicitly specified. [annotate]

    Note: throughout the specification, the words "instances of" are likely to be omitted when describing the behavior of instances of a class. [edit]-- Adlai Chandrasekhar 2021-03-19 18:29Z

    Some immutable classes also allow interning. A class is said to be interning if it guarantees that two instances that are equivalent will always be eq. For example, if the class color were interning, calling make-rgb-color twice with the same arguments would return eq values. CLIM does not specify that any class is interning, however all immutable classes are allowed to be interning at the discretion of the implementation. [annotate]

    In some rare cases, CLIM will modify objects that are members of immutable classes. Such objects are referred to as being volatile. Extreme care must be take with volatile objects. This specification will note whenever some object that is part of the API is volatile. [annotate]

    Note: s/must be take/must be taken/ [edit]-- Fred Feuerstein 5 2020-04-11 02:20Z

    2.4.1 Behavior of Interfaces

    In this specification, any interfaces that take or return mutable objects can be classified in a few different ways. [annotate]

    Most functions do not capture their mutable input objects, that is, these functions will either not store the objects at all, or will copy any mutable objects before storing them, or perhaps store only some of the components of the objects. Later modifications to those objects will not affect the internal state of CLIM. [annotate]

    Some functions may capture their mutable input objects. That is, it is unspecified as to whether a CLIM implementation will or will not capture the mutable inputs to some function. For such functions, programmers should assume that these objects will be captured and must not modify these objects capriciously. Furthermore, it is unspecifed what will happen if these objects are later modified. [annotate]

    Some programmers might choose to create a mutable subclass of an immutable class. If CLIM captures an object that is a member of such a class, it is unspecified what will happen if the programmer later modifies that object. If a programmer passes such an object to a CLIM function that may capture its inputs, he is responsible for either first copying the object or ensuring that the object does not change later. [annotate]

    Some functions that return mutable objects are guaranteed to create fresh outputs. These objects can be modified without affecting the internal state of CLIM. [annotate]

    Functions that return mutable objects that are not fresh objects fall into two categories: those that return read-only state, and those that return read/write state. If a function returns read-only state, programmers must not modify that object; doing so might corrupt the state of CLIM. If a function returns read/write state, the modification of that object is part of CLIM's interface, and programmers are free to modify the object in ways that "make sense". [annotate]