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

Last change on this file since 26886 was 26886, checked in by Kon Lovett, 9 years ago

Rel 1.0.1 thread-utils, 1.0.2 timed-resource.

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
23The {{OPENER}} is a {{(procedure () *)}} returning the resource object.
24
25The {{CLOSER}} is a {{(procedure (*))}} taking a resource object returned by
26the {{OPENER}}.
27
28The {{NAME}} is used as a prefix for the generated unique identifier of the
29created {{timed-resource}} and is usually a {{string}} or {{symbol}}. There is
30no semantic content.
31
32No attempt is made to serialize access to a resource, this is up to the caller;
33just don't share the thing.
34
35Exceptions occurring during resource acquisition or release abort the
36operation. Exceptions during resource release at shutdown are just displayed
37but no further action is taken.
38
39=== with-timed-resource
40
41<procedure>(with-timed-resource TIMED-RESOURCE ACTION) => *</procedure>
42
43Returns the result of invoking {{ACTION}} with the resource covered by the
44{{TIMED-RESOURCE}}. The acquired resource will not be released during the extent
45of the {{with-timed-resource}} invocation.
46
47{{ACTION}} is a {{(procedure (timed-resource) *)}}.
48
49=== timed-resource?
50
51<procedure>(timed-resource? OBJECT) => boolean</procedure>
52
53Is the {{OBJECT}} a {{timed-resource}}?
54
55=== timed-resource-name
56
57<procedure>(timed-resource-name TIMED-RESOURCE) => *</procedure>
58
59Returns unique id for {{TIMED-RESOURCE}}.
60
61=== timed-resource-timeout
62
63<procedure>(timed-resource-timeout) => (or #f number)</procedure>
64<procedure>(timed-resource-timeout SECONDS) => </procedure>
65
66Gets & sets the number of seconds to wait for a thread to quit.
67
68Default is {{#f}}.
69
70Currently only used at shutdown.
71
72
73== Examples
74
75<enscript language=scheme>
76(use timed-resource srfi-4)
77
78;; Returns a blob of random bits.
79;;
80;; (random-blob [BITS])
81;; BITS - the number of random bits, default is 128
82
83(define random-blob
84  (let ((tr-random-dev
85          (make-timed-resource
86            ;Use the random device (*nix only)
87            (lambda () (open-input-file "/dev/random" #:binary))
88            (lambda (port) (close-output-port port))
89            ;Only keep open for 10 seconds
90            10.0)))
91    (lambda (#!optional (bits 128))
92      (let ((bytes (inexact->exact (floor (/ (+ bits 7) 8)))))
93        (with-timed-resource tr-random-dev
94          (lambda (port)
95            (u8vector->blob (read-u8vector bytes))))) ) ) )
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
114== Author
115
116[[/users/kon-lovett|Kon Lovett]]
117
118
119== Version history
120
121; 1.0.2 : Use compiled setup-helper (& un-hide).
122; 1.0.1 : Fix for reporting an expected condition, ''timed-resource-closed'', during shutdown.
123; 1.0.0 : Moved from [[srfi-27]] into own extension.
124
125
126== License
127
128Copyright (C) 2010 Kon Lovett.  All rights reserved.
129
130Permission is hereby granted, free of charge, to any person obtaining a
131copy of this software and associated documentation files (the Software),
132to deal in the Software without restriction, including without limitation
133the rights to use, copy, modify, merge, publish, distribute, sublicense,
134and/or sell copies of the Software, and to permit persons to whom the
135Software is furnished to do so, subject to the following conditions:
136
137The above copyright notice and this permission notice shall be included
138in all copies or substantial portions of the Software.
139
140THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
141IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
142FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
143THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
144OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
145ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
146OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.