source: project/wiki/eggref/4/timed-resource @ 35443

Last change on this file since 35443 was 35443, checked in by Kon Lovett, 3 years ago

rel 1.1.0

File size: 4.3 KB
Line 
1[[tags: egg]]
2
3== timed-resource
4
5[[toc:]]
6
7
8== Documentation
9
10Provides an abstraction for a managed object, known as a resource, with a fixed
11lifetime. This might be used to create a file port that will automatically
12close if unused for some amount of time.
13
14=== make-timed-resource
15
16<procedure>(make-timed-resource OPENER CLOSER TIMEOUT [NAME]) -> timed-resource</procedure>
17
18Returns a new {{timed-resource}} object that covers a resource with a lifetime
19of {{TIMEOUT}} seconds. The resource is acquired by the {{OPENER}} and released
20by the {{CLOSER}}. An acquired resource will be released automatically at the
21end of its' life.
22
23; {{OPENER}} : {{(procedure () *)}} ; returns the {{resource-object}}
24; {{CLOSER}} : {{(procedure (*))}} ; takes the {{resource-object}} (returned by {{OPENER}})
25; {{TIMEOUT}} : {{number}} ; seconds
26; {{NAME}} : {{*}} ; prefix for the {{gensym}} of the created {{timed-resource}}
27
28No attempt is made to serialize access to a resource, this is up to the caller;
29just don't share the thing.
30
31Exceptions occurring during resource acquisition or release abort the
32operation. Exceptions during resource release at shutdown are just displayed
33but no further action is taken.
34
35=== with-timed-resource
36
37<procedure>(with-timed-resource TIMED-RESOURCE ACTION) -> *</procedure>
38
39Returns the result of invoking {{ACTION}} with the resource covered by the
40{{TIMED-RESOURCE}}. The acquired resource will not be released during the extent
41of the {{with-timed-resource}} invocation.
42
43{{ACTION}} is a {{(procedure (timed-resource) *)}}.
44
45=== timed-resource?
46=== check-timed-resource
47=== error-timed-resource
48
49<procedure>(timed-resource? OBJECT) -> boolean</procedure>
50
51Is the {{OBJECT}} a {{timed-resource}}?
52
53=== timed-resource-name
54
55<procedure>(timed-resource-name TIMED-RESOURCE) -> *</procedure>
56
57Returns unique id for {{TIMED-RESOURCE}}.
58
59=== default-timed-resource-timeout
60
61<procedure>(default-timed-resource-timeout) -> (or #f number)</procedure>
62<procedure>(default-timed-resource-timeout SECONDS) -> </procedure>
63
64Gets & sets the number of seconds to wait for a thread to quit.
65
66Default is {{#f}}.
67
68Currently only used at shutdown.
69
70
71== Examples
72
73<enscript language=scheme>
74(use timed-resource srfi-4)
75
76;; Returns a blob of random bits.
77;;
78;; (random-blob [BITS])
79;; BITS - the number of random bits, default is 128
80
81(define random-blob
82  (let (
83    (*tr-random-dev*
84      (make-timed-resource
85        ;random device (*nix only)
86        (lambda () (open-input-file "/dev/random" #:binary))
87        (lambda (port) (close-output-port port))
88        ;open for 10 seconds
89        10.0))
90    (round-bytes
91      (lambda (x) (fx/ (fx+ x 7) 8))) )
92    (lambda (#!optional (bits 128))
93      (with-timed-resource *tr-random-dev*
94        (lambda (port)
95          (u8vector->blob (read-u8vector (round-bytes bits))))) ) ) )
96</enscript>
97
98
99== Usage
100
101<enscript language=scheme>
102(require-extension timed-resource)
103</enscript>
104
105
106== Requirements
107
108[[thread-utils]]
109[[synch]]
110[[record-variants]]
111[[check-errors]]
112
113[[setup-helper]]
114
115
116== Author
117
118[[/users/kon-lovett|Kon Lovett]]
119
120
121== Version history
122
123; 1.1.0 : Add types.
124; 1.0.2 : Use compiled setup-helper (& un-hide).
125; 1.0.1 : Fix for reporting an expected condition, ''timed-resource-closed'', during shutdown.
126; 1.0.0 : Moved from [[srfi-27]] into own extension.
127
128
129== License
130
131Copyright (C) 2010-2017 Kon Lovett.  All rights reserved.
132
133Permission is hereby granted, free of charge, to any person obtaining a
134copy of this software and associated documentation files (the Software),
135to deal in the Software without restriction, including without limitation
136the rights to use, copy, modify, merge, publish, distribute, sublicense,
137and/or sell copies of the Software, and to permit persons to whom the
138Software is furnished to do so, subject to the following conditions:
139
140The above copyright notice and this permission notice shall be included
141in all copies or substantial portions of the Software.
142
143THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
144IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
145FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
146THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
147OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
148ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
149OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.