docs: function cache(item, options) {
      var dir_path = pathutils.join([
          item.conf.cache.base_path,
          pathutils.getHashPath(item.source),
      ]);
  
      var meta_path = pathutils.join([dir_path, "meta"]);
      var source_path = pathutils.join([dir_path, "source"]);
  
      if (item.source_type === "file" && !item.conf.cache.copy_source_file) {
          source_path = item.source;
      }
  
      var target_path = pathutils.join([dir_path, 'targets', pathutils.getOptionsPath(options)]);
  
      /*
       * lock the files in sequence, not in parallel
       * otherwise a deadlock with other request may occur
       */
      var promise = lock(source_path).then(function(l) {
          logging.debug(item.id, "Locked: source file");
          item.locks.source = l;
          return lock(meta_path);
      }).then(function(l) {
          logging.debug(item.id, "Locked: metadata");
          item.locks.meta = l;
          return lock(target_path);
      }).then(function(l) {
          logging.debug(item.id, "Locked: target file");
          item.locks.target = l;
          return item;
      }).
      then(function(item) {
          return meta_data_still_fresh(item);
      }).
      then(function(item) {
          //meta data is still fresh
          logging.debug(item.id, "Metadata is still fresh");
  
          return item;
      }, function(item) {
          //meta_data is stale or doesn't exist
          logging.debug(item.id, "Metadata is stale");
          //clear the item directory and download a new version of the source
          var source_promise = fsutils.cleardir(dir_path).
          then(function() {
              logging.debug(item.id, "Item directory cleared");
              logging.debug(item.id, "Requesting source", item.source);
              return source(item);
          }, function(err) {
              // clearing the directory failed.
              // maybe it didn't exists, which would be ok
              if (err.code === "ENOENT") {
                  logging.debug(item.id, "Requesting source", item.source);
                  return source(item);
              } else {
                  //no, it failed for some other reason
                  item.error = err;
                  throw item;
              }
          }).
          then(function(success) {
              //download succeeded
              logging.debug(item.id, "Source file ready");
              stats.download_success();
              //now only read metadata, don't evaluate headers or else
              //things with max-age=0 will always fail
              return read_meta_data(item);
          }, function(error) {
              logging.debug(item.id, "Acquiring source failed", error);
              stats.download_failure();
              throw item;
          });
  
          return source_promise;
      }).
      then(function(item) {
          //at this point the item is definitely fresh
          return get_target_file(item);
      }).
      then(function(item) {
          //the target has also been found. all done! \o/
          item.locks.meta();
          logging.debug(item.id, "Released lock: metadata");
          if (typeof item.locks.source === "function") {
              item.locks.source();
              logging.debug(item.id, "Released lock: source file");
          } else {
              //
          }
  
          register_for_gc(item);
          return item;
      },function(item) {
          item.locks.meta();
          logging.debug(item.id, "Released lock: metadata");
          item.locks.source();
          logging.debug(item.id, "Released lock: source file");
          item.locks.target();
          logging.debug(item.id, "Released lock: target file");
  
          register_for_gc(item);
          throw item;
      });
  
      return promise;
  }