▼Disposable Values
►4 Batteries-Included Disposables
On this page:
4.1 Filesystem Disposables
disposable-file
disposable-file-logger
disposable-directory
disposable-directory-logger
4.2 Utilities for Testing Disposables
sequence->disposable
disposable/  event-log
event-log?
event-log-events
4.3 Example Disposables
example-disposable
7.7
  top  ← prev  up  next → 

4 Batteries-Included Disposables

The disposable library includes a few extra modules that provide specialized disposables for various purposes.

    4.1 Filesystem Disposables

    4.2 Utilities for Testing Disposables

    4.3 Example Disposables

4.1 Filesystem Disposables

 (require disposable/file) package: disposable

procedure

(disposable-file [#:contents contents 
  #:parent-dir parent-dir]) 
 → (disposable/c path-string?)
  contents : string? = ""
  parent-dir : path-string? = (find-system-dir 'temp-dir)
Returns a disposable that allocates a temporary file in parent-dir containing contents and deletes the file upon deallocation. If the file is deleted before disposal occurs, or the same file is disposed twice, no error occurs but an event is logged to disposable-file-logger.

Example:
> (with-disposable ([tmpfile (disposable-file #:contents "foo")])
    (printf "Created temporary file ~a\n" tmpfile)
    (printf "Contents = ~a\n" (file->string tmpfile)))

Created temporary file /var/tmp/rkttmp15884897851588489785406

Contents = foo

value

disposable-file-logger : logger?

A logger used by disposable-file whenever an allocated file is already deleted at the time of disposal. Events are logged at the 'info level with the topic 'disposable-file.

procedure

(disposable-directory [#:parent-dir parent-dir])

 → (disposable/c path-string?)
  parent-dir : path-string? = (find-system-dir 'temp-dir)
Retuns a disposable that allocates a temporary directory in parent-dir and deletes the directory upon deallocation. If the directory is deleted before disposal occurs, or the same directory is disposed twice, no error occurs but an event is logged to disposable-directory-logger.

Example:
> (with-disposable ([tmpdir (disposable-directory)])
    (with-disposable ([child (disposable-file #:parent-dir tmpdir)])
      (printf "File = ~a\n" child)
      (printf "Directory children = ~a\n" (directory-list tmpdir))))

File = /var/tmp/rkttmp15884897861588489786103/rkttmp15884897861588489786103

Directory children = (rkttmp15884897861588489786103)

value

disposable-directory-logger : logger?

A logger used by disposable-directory whenever an allocated directory is already deleted at the time of disposal. Events are logged at the 'info level with the topic 'disposable-directory.

4.2 Utilities for Testing Disposables

 (require disposable/testing) package: disposable

This module provides utilities for testing operations involving disposables. The bindings provided here are designed for testing purposes only, and are not intended for use in production environments.

procedure

(sequence->disposable seq) → disposable?

  seq : sequence?
Starts traversing seq with sequence-generate, then returns a disposable that allocates values by returning the next value from the traversal of seq. Deallocation does nothing. This is intended for testing code that manipulates a disposable.

Examples:
> (define abc-disp (sequence->disposable '(a b c)))
> (with-disposable ([item abc-disp])
    (printf "Acquired ~v\n" item))

Acquired 'a

> (with-disposable ([item abc-disp])
    (printf "Acquired ~v\n" item))

Acquired 'b

procedure

(disposable/event-log disp)

 → (disposable/c (list/c disposable? event-log?))
  disp : disposable?
Returns a disposable that allocates an event log and a wrapper around disp that records allocations and deallocations in the allocated event log. An event log contains a list of events, where each event is a list whose first item is either 'alloc or 'dealloc and whose second item is the allocated or deallocated value.

Examples:
> (define ex/log (disposable/event-log example-disposable))
> (with-disposable ([ex+log-list ex/log])
    (define ex (first ex+log-list))
    (define elog (second ex+log-list))
    (with-disposable ([n ex])
      (printf "Acquired ~v\n" n))
    (with-disposable ([n ex])
      (printf "Acquired ~v\n" n))
    (event-log-events elog))

Allocated 29

Acquired 29

Deallocated 29

Allocated 61

Acquired 61

Deallocated 61

'((alloc 29) (dealloc 29) (alloc 61) (dealloc 61))

procedure

(event-log? v) → boolean?

  v : any/c
Predicate identifying event log values. See disposable/event-log.

procedure

(event-log-events elog)

 → (listof (list/c (or/c 'alloc 'dealloc) any/c))
  elog : event-log?
Returns a list of events that are currently in elog. Events are returned in order of oldest to newest. See disposable/event-log.

4.3 Example Disposables

 (require disposable/example) package: disposable

Resource allocation can be tricky to showcase in documentation, so the disposable/example module provides a simple example-disposable that "allocates" a random number while printing a message to current-output-port during allocation and deallocation. This is used to help users visualize the timeline of disposable values when reading documentation. It is not considered a stable part of disposable, and is only documented to provide hyperlinks at use sites.

value

example-disposable : (disposable/c (integer-in 0 99))

A disposable used in documentation that displays a message when called for allocation and deallocation. Returns a small random number when asked to allocate a value.

  top  ← prev  up  next →