▼Disposable Values
►3 Transient Values
On this page:
3.1 Definition and Construction
transient?
transient/  c
disposable-transient
3.2 Manipulating Transients
transient-dispose
transient-acquire
transient-get
transient-refresh
8.16.0.4
  top  contents    up   

3 Transient Values🔗ℹ

A transient value is a wrapper around a value allocated by a disposable that allows users of the value to have some limited control over its lifecycle. In particular, users of a transient may:

Any disposable may be converted to a disposable of a transient value by using disposable-transient. Transients are intended for lightweight control of disposable allocation and deallocation in a way that cooperates with other disposable wrappers and combinators. For example, combining transients with disposable-pool allows values to be reused and allows clients to explicitly create and destroy pooled values if needed.

Transients are thread safe, but not thread isolated. A transient either contains one allocated value or contains no values, and multiple threads may call any of the above functions on transients without violating this consistency. However, the above functions will block if a new value needs to be allocated or deallocated. To acquire disposables in a thread isolated manner where each thread has unfettered access to its own private instance of a disposable, see acquire-virtual.

All of the bindings documented in this section are provided by disposable.

3.1 Definition and Construction🔗ℹ

procedure

(transient? v) → boolean?

  v : any/c
Returns #t if v is a transient, returns #f otherwise.

Added in version 0.3 of package disposable.

procedure

(transient/c c) → contract?

  c : contract?
Returns a contract that recognizes transients that own values that satisfy c. The returned contract monitors all future values that a transient might allocate in addition to checking its current value.

Added in version 0.3 of package disposable.

procedure

(disposable-transient disp) → (disposable/c transient?)

  disp : disposable?
Returns a disposable that wraps values allocated by disp in a transient. Disposal of the transient disposes its underlying value using transient-dispose.

Example:
> (with-disposable ([t (disposable-transient example-disposable)])
    (printf "Acquired transient: ~a\n" (transient-acquire t))
    (transient-refresh t)
    (printf "Refreshed transient: ~a\n" (transient-acquire t)))

Allocated 89

Acquired transient: 89

Deallocated 89

Allocated 90

Refreshed transient: 90

Deallocated 90

Added in version 0.3 of package disposable.

3.2 Manipulating Transients🔗ℹ

procedure

(transient-dispose t) → void?

  t : transient?
Disposes the currently allocated value of t if one exists. A value owned by a transient will never be deallocated twice — repeated calls to transient-dispose on the same transient have no effect. The disposable returend by disposable-transient calls transient-dispose upon deallocation.

After disposal of the value owned by t, calling transient-acquire will block on allocating a fresh value while transient-get will return #f.

Example:
> (with-disposable ([t (disposable-transient example-disposable)])
    (transient-dispose t))

Allocated 94

Deallocated 94

Added in version 0.3 of package disposable.

procedure

(transient-acquire t) → any/c

  t : transient?
Returns the allocated value of t. If t does not currently own an allocated value (due to a previous use of transient-dispose) a fresh value is created inside t using the disposable that t was constructed with. See also transient-get which returns #f instead of allocating a new value.

Example:
> (with-disposable ([t (disposable-transient example-disposable)])
    (transient-dispose t)
    (printf "Acquired transient: ~a\n" (transient-acquire t)))

Allocated 45

Deallocated 45

Allocated 93

Acquired transient: 93

Deallocated 93

Added in version 0.3 of package disposable.

procedure

(transient-get t) → any/c

  t : transient?
Returns the allocated value of t or #f if t does not currently own an allocated value (due to a previous use of transient-dispose). In general, prefer using transient-acquire unless there is a specific reason to avoid allocating a fresh value.

Example:
> (with-disposable ([t (disposable-transient example-disposable)])
    (transient-dispose t)
    (printf "Transient value: ~a\n" (transient-get t)))

Allocated 77

Deallocated 77

Transient value: #f

Added in version 0.3 of package disposable.

procedure

(transient-refresh t) → any/c

  t : transient?
Disposes the allocated value owned by t if one exists, then allocates a fresh value inside t and returns that value. Equivalent to calling (transient-dispose t) followed by (transient-acquire t).

Example:
> (with-disposable ([t (disposable-transient example-disposable)])
    (printf "Refreshed value: ~a\n" (transient-refresh t)))

Allocated 28

Deallocated 28

Allocated 68

Refreshed value: 68

Deallocated 68

Added in version 0.3 of package disposable.

  top  contents    up