def set( key:, payload:, maximum_lifespan: nil )
      key = normalise_key( key, 'set' )

      if payload.nil?
        raise "Hoodoo::TransientStore\#set: Payloads of 'nil' are prohibited"
      end

      maximum_lifespan ||= @default_maximum_lifespan

      begin
        result = @storage_engine_instance.set(
          key:              key,
          payload:          payload,
          maximum_lifespan: maximum_lifespan
        )

        if result != true && result != false
          raise "Hoodoo::TransientStore\#set: Engine '#{ @storage_engine }' returned an invalid response"
        end

      rescue => e
        result = e

      end

      return result
    end
def set( key:, payload:, maximum_lifespan: nil )
      key = normalise_key( key, 'set' )

      if payload.nil?
        raise "Hoodoo::TransientStore\#set: Payloads of 'nil' are prohibited"
      end

      maximum_lifespan ||= @default_maximum_lifespan

      begin
        result = @storage_engine_instance.set(
          key:              key,
          payload:          payload,
          maximum_lifespan: maximum_lifespan
        )

        if result != true && result != false
          raise "Hoodoo::TransientStore\#set: Engine '#{ @storage_engine }' returned an invalid response"
        end

      rescue => e
        result = e

      end

      return result
    end
Instantiate a new Transient storage object through which temporary data
 can be stored or retrieved.

 The TransientStore abstraction is a high level and simple abstraction over
 heterogenous data storage engines. It does not expose the many subtle
 configuration settings usually available in such. If you need to take
 advantage of those at an item storage level, you'll need to use a lower
 level interface and thus lock your code to the engine of choice.

 Engine plug-ins are recommended to attempt to gain and test a connection
 to the storage engine when this object is constructed, so if building a
 TransientStore instance, ensure your chosen storage engine is running
 first. Exceptions may be raised by storage engines, so you will probably
 want to catch those with more civilised error handling code.

 _Named_ parameters are:

 +storage_engine+::           An entry from ::supported_storage_engines.

 +storage_host_uri+::         The engine-dependent connection URI. Consult
                              documentation for your chosen engine to find
                              out its connection URI requirements, along
                              with the documentation for the constructor
                              method of the plug-in in use, since in some
                              cases requirements may be unusual (e.g. in
                              Hoodoo::TransientStore::MemcachedRedisMirror).

 +default_maximum_lifespan+:: The default time-to-live for data items, in,
                              seconds; can be overridden per item; default
                              is 604800 seconds or 7 days.

 +default_namespace+::        Storage engine keys are namespaced with
                              +nz_co_loyalty_hoodoo_transient_store_+ by
                              default, though this can be overridden here.
                              Pass a String or Symbol.

 Set (write) a given payload into the storage engine with the given
 payload and maximum lifespan.

 Payloads must only contain simple types such as Hash, Array, String and
 Integer. Complex types like Symbol, Date, Float, BigDecimal or custom
 objects are unlikely to serialise properly but since this depends upon
 the storage engine in use, errors may or may not be raised for misuse.

 Storage engines usually have a maximum payload size limit; consult your
 engine administrator for information. For example, the default - but
 reconfigurable - maximum payload size for Memcached is 1MB.

 For maximum possible compatibility:

 * Use only Hash payloads with String key/value paids and no nesting. You
   may choose to marshal the data into a String manually for unusual data
   requirements, manually converting back when reading stored data.

 * Keep the payload size as small as possible - large objects belong in
   bulk storage engines such as Amazon S3.

 These are only guidelines though - heterogenous storage engine support
 and the ability of system administrators to arbitrarily configure those
 storage engines makes it impossible to be more precise.

 Returns:

 * +true+ if storage was successful
 * +false+ if storage failed but the reason is unknown
 * An +Exception+ instance if storage failed and the storage engine
   raised an exception describing the problem.

 _Named_ parameters are:

 +key+::              Storage key to use in the engine, which is then used
                      in subsequent calls to #get and possibly eventually
                      to #delete. Only non-empty Strings or Symbols are
                      permitted, else an exception will be raised.

 +payload+::          Payload data to store under the given +key+. A flat
                      Hash is recommended rather than simple types such as
                      String (unless marshalling a complex type into such)
                      in order to make potential additions to stored data
                      easier to implement. Note that +nil+ is prohibited.

 +maximum_lifespan+:: Optional maximum lifespan, seconds. Storage engines
                      may chooset to evict payloads sooner than this; it
                      is a maximum time, not a guarantee. Omit to use this
                      TransientStore instance's default value - see ::new.
                      If you know you no longer need a piece of data at a
                      particular point in the execution flow of your code,
                      explicitly delete it via #delete rather than leaving
                      it to expire. This maximises the storage engine's
                      pool free space and so minimises the chance of early
                      item eviction.