lazy_data 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5e20fa1b668d1f8e85d3a12faee85f1516e992ff4f630a365788f9087e323d7
-  data.tar.gz: 5f51aeb56da1b19b51e5196eef0587875185c7c591c01d00077ad7a0919ceec8
+  metadata.gz: d18a78e450308fdbb793e1152f5dbe8ed410468be1260bceb5bdd20a200371a7
+  data.tar.gz: d9b5efd1783d67c8b17b7d5284a5808f4ba54a6fddb0a4147169d3c5c4fe31d0
 SHA512:
-  metadata.gz: 33399a11557e99a0caf729e44ef433fa8aa6278c3b08f96d08c3c933c51d944a933afb5e3290e44e45312b8bc2392c0b160d97b22ebaa35323ca33710e3f13eb
-  data.tar.gz: 9e101926c39f9d071ee629abbaf5a0415341d722df0f13e63758ab7fccf135c9066908bfd68b99017b58c496637e4e65b5019c40c3746ce52cd67a89faa066c4
+  metadata.gz: 0057544c92c2023815506435dba1c5b5f57d3829b0fbeff1a41f7a555ea69a109aeb16fb75beeef342f14096f800962055fa2f5d9a4d5a2d970428506de8d376
+  data.tar.gz: 3fa2b253ea08db8f9237e3f35f3132f5e87c5e9b1868fd7af05f1760ff1f66bb6e23b0c9bffd4457de05e00b586bbffc647b40844929f398ff6492079a49c9be

data/.yardopts

@@ -0,0 +1,11 @@
+--no-private
+--title=LazyData
+--markup=markdown
+--markup-provider redcarpet
+--main=README.md
+./lib/lazy_data/**/*.rb
+./lib/lazy_data.rb
+-
+README.md
+LICENSE.md
+CHANGELOG.md

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Releases
+
+### v0.1.0 / 2026-03-19
+
+* ADDED: Initial extraction of lazy_data from google-cloud-env

data/LICENSE.md

@@ -0,0 +1,201 @@
+                                 Apache License
+                            Version 2.0, January 2004
+                         http://www.apache.org/licenses/
+
+    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+    1. Definitions.
+
+       "License" shall mean the terms and conditions for use, reproduction,
+       and distribution as defined by Sections 1 through 9 of this document.
+
+       "Licensor" shall mean the copyright owner or entity authorized by
+       the copyright owner that is granting the License.
+
+       "Legal Entity" shall mean the union of the acting entity and all
+       other entities that control, are controlled by, or are under common
+       control with that entity. For the purposes of this definition,
+       "control" means (i) the power, direct or indirect, to cause the
+       direction or management of such entity, whether by contract or
+       otherwise, or (ii) ownership of fifty percent (50%) or more of the
+       outstanding shares, or (iii) beneficial ownership of such entity.
+
+       "You" (or "Your") shall mean an individual or Legal Entity
+       exercising permissions granted by this License.
+
+       "Source" form shall mean the preferred form for making modifications,
+       including but not limited to software source code, documentation
+       source, and configuration files.
+
+       "Object" form shall mean any form resulting from mechanical
+       transformation or translation of a Source form, including but
+       not limited to compiled object code, generated documentation,
+       and conversions to other media types.
+
+       "Work" shall mean the work of authorship, whether in Source or
+       Object form, made available under the License, as indicated by a
+       copyright notice that is included in or attached to the work
+       (an example is provided in the Appendix below).
+
+       "Derivative Works" shall mean any work, whether in Source or Object
+       form, that is based on (or derived from) the Work and for which the
+       editorial revisions, annotations, elaborations, or other modifications
+       represent, as a whole, an original work of authorship. For the purposes
+       of this License, Derivative Works shall not include works that remain
+       separable from, or merely link (or bind by name) to the interfaces of,
+       the Work and Derivative Works thereof.
+
+       "Contribution" shall mean any work of authorship, including
+       the original version of the Work and any modifications or additions
+       to that Work or Derivative Works thereof, that is intentionally
+       submitted to Licensor for inclusion in the Work by the copyright owner
+       or by an individual or Legal Entity authorized to submit on behalf of
+       the copyright owner. For the purposes of this definition, "submitted"
+       means any form of electronic, verbal, or written communication sent
+       to the Licensor or its representatives, including but not limited to
+       communication on electronic mailing lists, source code control systems,
+       and issue tracking systems that are managed by, or on behalf of, the
+       Licensor for the purpose of discussing and improving the Work, but
+       excluding communication that is conspicuously marked or otherwise
+       designated in writing by the copyright owner as "Not a Contribution."
+
+       "Contributor" shall mean Licensor and any individual or Legal Entity
+       on behalf of whom a Contribution has been received by Licensor and
+       subsequently incorporated within the Work.
+
+    2. Grant of Copyright License. Subject to the terms and conditions of
+       this License, each Contributor hereby grants to You a perpetual,
+       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+       copyright license to reproduce, prepare Derivative Works of,
+       publicly display, publicly perform, sublicense, and distribute the
+       Work and such Derivative Works in Source or Object form.
+
+    3. Grant of Patent License. Subject to the terms and conditions of
+       this License, each Contributor hereby grants to You a perpetual,
+       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+       (except as stated in this section) patent license to make, have made,
+       use, offer to sell, sell, import, and otherwise transfer the Work,
+       where such license applies only to those patent claims licensable
+       by such Contributor that are necessarily infringed by their
+       Contribution(s) alone or by combination of their Contribution(s)
+       with the Work to which such Contribution(s) was submitted. If You
+       institute patent litigation against any entity (including a
+       cross-claim or counterclaim in a lawsuit) alleging that the Work
+       or a Contribution incorporated within the Work constitutes direct
+       or contributory patent infringement, then any patent licenses
+       granted to You under this License for that Work shall terminate
+       as of the date such litigation is filed.
+
+    4. Redistribution. You may reproduce and distribute copies of the
+       Work or Derivative Works thereof in any medium, with or without
+       modifications, and in Source or Object form, provided that You
+       meet the following conditions:
+
+       (a) You must give any other recipients of the Work or
+           Derivative Works a copy of this License; and
+
+       (b) You must cause any modified files to carry prominent notices
+           stating that You changed the files; and
+
+       (c) You must retain, in the Source form of any Derivative Works
+           that You distribute, all copyright, patent, trademark, and
+           attribution notices from the Source form of the Work,
+           excluding those notices that do not pertain to any part of
+           the Derivative Works; and
+
+       (d) If the Work includes a "NOTICE" text file as part of its
+           distribution, then any Derivative Works that You distribute must
+           include a readable copy of the attribution notices contained
+           within such NOTICE file, excluding those notices that do not
+           pertain to any part of the Derivative Works, in at least one
+           of the following places: within a NOTICE text file distributed
+           as part of the Derivative Works; within the Source form or
+           documentation, if provided along with the Derivative Works; or,
+           within a display generated by the Derivative Works, if and
+           wherever such third-party notices normally appear. The contents
+           of the NOTICE file are for informational purposes only and
+           do not modify the License. You may add Your own attribution
+           notices within Derivative Works that You distribute, alongside
+           or as an addendum to the NOTICE text from the Work, provided
+           that such additional attribution notices cannot be construed
+           as modifying the License.
+
+       You may add Your own copyright statement to Your modifications and
+       may provide additional or different license terms and conditions
+       for use, reproduction, or distribution of Your modifications, or
+       for any such Derivative Works as a whole, provided Your use,
+       reproduction, and distribution of the Work otherwise complies with
+       the conditions stated in this License.
+
+    5. Submission of Contributions. Unless You explicitly state otherwise,
+       any Contribution intentionally submitted for inclusion in the Work
+       by You to the Licensor shall be under the terms and conditions of
+       this License, without any additional terms or conditions.
+       Notwithstanding the above, nothing herein shall supersede or modify
+       the terms of any separate license agreement you may have executed
+       with Licensor regarding such Contributions.
+
+    6. Trademarks. This License does not grant permission to use the trade
+       names, trademarks, service marks, or product names of the Licensor,
+       except as required for reasonable and customary use in describing the
+       origin of the Work and reproducing the content of the NOTICE file.
+
+    7. Disclaimer of Warranty. Unless required by applicable law or
+       agreed to in writing, Licensor provides the Work (and each
+       Contributor provides its Contributions) on an "AS IS" BASIS,
+       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+       implied, including, without limitation, any warranties or conditions
+       of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+       PARTICULAR PURPOSE. You are solely responsible for determining the
+       appropriateness of using or redistributing the Work and assume any
+       risks associated with Your exercise of permissions under this License.
+
+    8. Limitation of Liability. In no event and under no legal theory,
+       whether in tort (including negligence), contract, or otherwise,
+       unless required by applicable law (such as deliberate and grossly
+       negligent acts) or agreed to in writing, shall any Contributor be
+       liable to You for damages, including any direct, indirect, special,
+       incidental, or consequential damages of any character arising as a
+       result of this License or out of the use or inability to use the
+       Work (including but not limited to damages for loss of goodwill,
+       work stoppage, computer failure or malfunction, or any and all
+       other commercial damages or losses), even if such Contributor
+       has been advised of the possibility of such damages.
+
+    9. Accepting Warranty or Additional Liability. While redistributing
+       the Work or Derivative Works thereof, You may choose to offer,
+       and charge a fee for, acceptance of support, warranty, indemnity,
+       or other liability obligations and/or rights consistent with this
+       License. However, in accepting such obligations, You may act only
+       on Your own behalf and on Your sole responsibility, not on behalf
+       of any other Contributor, and only if You agree to indemnify,
+       defend, and hold each Contributor harmless for any liability
+       incurred by, or claims asserted against, such Contributor by reason
+       of your accepting any such warranty or additional liability.
+
+    END OF TERMS AND CONDITIONS
+
+    APPENDIX: How to apply the Apache License to your work.
+
+       To apply the Apache License to your work, attach the following
+       boilerplate notice, with the fields enclosed by brackets "[]"
+       replaced with your own identifying information. (Don't include
+       the brackets!)  The text should be enclosed in the appropriate
+       comment syntax for the file format. We also recommend that a
+       file or class name and description of purpose be included on the
+       same "printed page" as the copyright notice for easier
+       identification within third-party archives.
+
+    Copyright [yyyy] [name of copyright owner]
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.

data/README.md

@@ -1,9 +1,181 @@
-# Placeholder for lazy_data
+# LazyData
 
-This is a placeholder gem, which was generated on 2026-03-16 to
-reserve the gem "lazy_data".
-The actual gem is planned for release in the near future.
+LazyData provides data types featuring thread-safe lazy computation. These
+objects are constructed with a block that can be called to compute the final
+value, but it is not actually called until the value is requested. Once
+requested, the computation takes place only once, in the first thread that
+requested the value. Future requests will return a cached value. Furthermore,
+any other threads that request the value during the initial computation will
+block until the first thread has completed the computation. This implementation
+also provides retry and expiration features. The code was extracted from the
+google-cloud-env gem that originally used it.
 
-If this is a problem, or if the actual gem has not been released
-in a timely manner, you can contact the owner at
-`dazuma@gmail.com`.
+## Quick start
+
+Install lazy_data as a gem, or include it in your bundle.
+
+```sh
+gem install lazy_data
+```
+
+You can use `LazyData::Value` to lazily load or compute a single value. For
+example, to load a web page:
+
+```ruby
+require "lazy_data"
+
+# Creating a lazy value does not compute the value yet
+lazy_content = LazyData::Value.new do
+  require "net/http"
+  Net::HTTP.get(URI("https://example.com"))
+end
+
+# The block runs and computes the value the first time the value is requested
+content = lazy_content.get
+
+# The computed value is cached, and subsequent requests return it
+content2 = lazy_content.get
+```
+
+Importantly, `LazyData::Value` is thread-safe, and if multiple threads request
+the value concurrently, only one thread will run the computation, while the
+others will block until it completes.
+
+## Features
+
+LazyData is similar to `Concurrent::Delay`, part of the
+[concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) gem.
+However, it includes a number of additional features that were driven by use
+cases from [google-cloud-env](https://github.com/googleapis/ruby-cloud-env),
+from which the library was extracted. Among those:
+
+### Retries
+
+LazyData can be configured to retry failed computations, with minimum delays
+between retries.
+
+```ruby
+require "lazy_data"
+
+# Configure 5 tries with exponential backoff
+retry_config = LazyData::Retries.new(max_tries: 5,
+                                     initial_delay: 1,
+                                     delay_multiplier: 1.5,
+                                     max_delay: 10)
+
+# The computation itself is unchanged
+lazy_content = LazyData::Value.new(retries: retry_config) do
+  require "net/http"
+  Net::HTTP.get(URI("https://example.com"))
+end
+
+# Make repeated attempts to get the content, respecting the backoff setting
+content = lazy_content.await
+
+# Or make single attempts and retry manually
+content = begin
+  lazy_content.get
+rescue StandardError => e
+  # If the first attempt failed, and we retry immediately, this second
+  # attempt could just reraised the cached exception if it happened before
+  # the configured delay
+  lazy_content.get # Likely reraises
+end
+```
+
+### Expiration
+
+Computed values can expire after a configured period of time, so that the next
+subsequent request triggers the computation again.
+
+```ruby
+require "lazy_data"
+
+# Modify the computation to return results that expire after 1 minute, or
+# raise an error that will expire after 1 minute.
+lazy_content = LazyData::Value do
+  require "net/http"
+  content = Net::HTTP.get(URI("https://example.com"))
+  LazyData.expiring_value(60, content)
+rescue StandardError => e
+  LazyData.raise_expiring_error(60, e)
+end
+
+# Perform the computation to get the data
+content = lazy_content.get
+
+# Rerunning immediately will return the cached value which has not expired
+content2 = lazy_content.get
+
+# If we wait for the value to expire, the computation will run again
+sleep(61)
+content3 = lazy_content.get
+```
+
+### Lower-level API
+
+In case you need more low-level control, the API provides advanced methods that
+can set the value immediately, expire the value immediately, or query the
+internal state.
+
+```ruby
+require "lazy_data"
+
+lazy_content = LazyData::Value.new do
+  require "net/http"
+  Net::HTTP.get(URI("https://example.com"))
+end
+
+# Bypass the normal computation and set the value immediately
+lazy_content.set!("Hello, world!")
+
+# Retrieving the value does not perform computation but returns the manually
+# cached value
+content = lazy_content.get
+
+# Expire the current value immediately
+lazy_content.expire!
+
+# Now retrieving the value will call the compute block
+content2 = lazy_content.get
+```
+
+## Contributing
+
+Development is done in GitHub at https://github.com/dazuma/lazy_data.
+
+*   To file issues: https://github.com/dazuma/lazy_data/issues.
+*   For questions and discussion, please do not file an issue. Instead, use the
+    discussions feature: https://github.com/dazuma/lazy_data/discussions.
+*   Pull requests are welcome, but I recommend first filing an issue, and/or
+    discussing substantial changes in GitHub discussions, before implementing.
+
+The library uses [toys](https://dazuma.github.io/toys) for testing and CI. To
+run the test suite, `gem install toys` and then run `toys ci`. You can also run
+unit tests, rubocop, and build tests independently.
+
+## Copyright and licensing notes
+
+This code was originally written by Daniel Azuma while working at Google, and
+was part of the [google-cloud-env](https://github.com/googleapis/ruby-cloud-env)
+gem. Because of that, the library is Apache 2.0 licensed, and portions remain
+copyright Google, LLC. Daniel subsequently extracted and forked this library by
+itself, and has continued to develop the fork. The original remains vendored in
+the google-cloud-env code base.
+
+    Portions copyright 2023 Google LLC
+
+    This code has been modified from the original Google code. The modified
+    portions copyright 2026 Daniel Azuma
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.

data/lib/lazy_data/dict.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+# Portions copyright 2023 Google LLC
+#
+# This code has been modified from the original Google code. The modified
+# portions copyright 2026 Daniel Azuma
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module LazyData
+  ##
+  # This expands on {LazyData::Value} by providing a lazy key-value dictionary.
+  # Each key uses a separate {LazyData::Value}; hence multiple keys can be in
+  # the process of computation concurrently and independently.
+  #
+  class Dict
+    ##
+    # Create a LazyData::Dict.
+    #
+    # You must pass a block that will be called to compute the value the first
+    # time it is accessed. The block takes the key as an argument and should
+    # evaluate to the value for that key, or raise an exception on error. To
+    # specify a value that expires, use {LazyData.expiring_value}. To raise an
+    # exception that expires, use {LazyData.raise_expiring_error}.
+    #
+    # You can optionally pass a retry manager, which controls how subsequent
+    # accesses might try calling the block again if a compute attempt fails
+    # with an exception. A retry manager should either be an instance of
+    # {LazyData::Retries} or an object that duck types it.
+    #
+    # @param retries [Retries,Proc] A retry manager. The default is a retry
+    #     manager that tries only once. You can provide either a static retry
+    #     manager or a Proc that returns a retry manager.
+    # @param lifetime [Numeric,nil] The default lifetime of a computed value.
+    #     Optional. No expiration by default if not provided. This can be
+    #     overridden in the block by returning {LazyData.expiring_value} or
+    #     calling {LazyData.raise_expiring_error} explicitly.
+    # @param block [Proc] A block that can be called to attempt to compute the
+    #     value given the key.
+    #
+    def initialize(retries: nil, lifetime: nil, &block)
+      @retries = retries
+      @default_lifetime = lifetime
+      @compute_handler = block
+      @key_values = {}
+      @mutex = ::Thread::Mutex.new
+    end
+
+    ##
+    # Returns the value for the given key. This will either return the value or
+    # raise an error indicating failure to compute the value. If the value was
+    # previously cached, it will return that cached value, otherwise it will
+    # either run the computation to try to determine the value, or wait for
+    # another thread that is already running the computation.
+    #
+    # Any arguments beyond the initial key argument will be passed to the block
+    # if it is called, but are ignored if a cached value is returned.
+    #
+    # @param key [Object] the key
+    # @param extra_args [Array] extra arguments to pass to the block
+    # @return [Object] the value
+    # @raise [Exception] if an error happened while computing the value
+    #
+    def get(key, *extra_args)
+      lookup_key(key).get(key, *extra_args)
+    end
+    alias [] get
+
+    ##
+    # This method calls {#get} repeatedly until a final result is available or
+    # retries have exhausted.
+    #
+    # Note: this method spins on {#get}, although honoring any retry delay.
+    # Thus, it is best to call this only if retries are limited or a retry
+    # delay has been configured.
+    #
+    # @param key [Object] the key
+    # @param extra_args [Array] extra arguments to pass to the block
+    # @param transient_errors [Array<Class>] An array of exception classes that
+    #     will be treated as transient and will allow await to continue
+    #     retrying. Exceptions omitted from this list will be treated as fatal
+    #     errors and abort the call. Default is `[StandardError]`.
+    # @param max_tries [Integer,nil] The maximum number of times this will call
+    #     {#get} before giving up, or nil for a potentially unlimited number of
+    #     attempts. Default is 1.
+    # @param max_time [Numeric,nil] The maximum time in seconds this will spend
+    #     before giving up, or nil (the default) for a potentially unlimited
+    #     timeout.
+    #
+    # @return [Object] the value
+    # @raise [Exception] if a fatal error happened, or retries have been
+    #     exhausted.
+    #
+    def await(key, *extra_args, transient_errors: nil, max_tries: 1, max_time: nil)
+      lookup_key(key).await(key, *extra_args,
+                            transient_errors: transient_errors,
+                            max_tries: max_tries,
+                            max_time: max_time)
+    end
+
+    ##
+    # Returns the current low-level state for the given key. Does not block for
+    # computation. See {LazyData::Value#internal_state} for details.
+    #
+    # @param key [Object] the key
+    # @return [Array] the low-level state
+    #
+    def internal_state(key)
+      lookup_key(key).internal_state
+    end
+
+    ##
+    # Force the cache for the given key to expire immediately, if computation
+    # is complete.
+    #
+    # Any cached value will be cleared, the retry count is reset, and the next
+    # access will call the compute block as if it were the first access.
+    # Returns true if this took place. Has no effect and returns false if the
+    # computation is not yet complete (i.e. if a thread is currently computing,
+    # or if the last attempt failed and retries have not yet been exhausted.)
+    #
+    # @param key [Object] the key
+    # @return [true,false] whether the cache was expired
+    #
+    def expire!(key)
+      lookup_key(key).expire!
+    end
+
+    ##
+    # Force the values for all keys to expire immediately.
+    #
+    # @return [Array<Object>] A list of keys that were expired. A key is *not*
+    #     included if its computation is not yet complete (i.e. if a thread is
+    #     currently computing, or if the last attempt failed and retries have
+    #     not yet been exhausted.)
+    #
+    def expire_all!
+      all_expired = []
+      @mutex.synchronize do
+        @key_values.each do |key, value|
+          all_expired << key if value.expire!
+        end
+      end
+      all_expired
+    end
+
+    ##
+    # Set the cache value for the given key explicitly and immediately. If a
+    # computation is in progress, it is "detached" and its result will no
+    # longer be considered.
+    #
+    # @param key [Object] the key
+    # @param value [Object] the value to set
+    # @param lifetime [Numeric] the lifetime until expiration in seconds, or
+    #     nil (the default) for no expiration.
+    # @return [Object] the value
+    #
+    def set!(key, value, lifetime: nil)
+      lookup_key(key).set!(value, lifetime: lifetime)
+    end
+
+    private
+
+    ##
+    # Ensures that exactly one LazyData::Value exists for the given key, and
+    # returns it.
+    #
+    def lookup_key(key)
+      @mutex.synchronize do
+        if @key_values.key?(key)
+          @key_values[key]
+        else
+          retries =
+            if @retries.respond_to?(:reset_dup)
+              @retries.reset_dup
+            elsif @retries.respond_to?(:call)
+              @retries.call
+            end
+          @key_values[key] = Value.new(retries: retries, lifetime: @default_lifetime, &@compute_handler)
+        end
+      end
+    end
+  end
+end