Home

Traffic Server Software Developers Kit

Prev — INKCacheReady
INKCacheRemove — Next

INKCacheWrite

Initiates writing an object to the Traffic Server cache.

Prototype

INKAction INKCacheWrite (INKCont contp, INKCacheKey key)

Arguments

INKCont contp is the continuation the cache calls back (telling it whether the write operation can proceed).

INKCacheKey key is the cache key that corresponds to the object to be cached.

Description

Asks the Traffic Server cache if contp can start writing the object (corresponding to key) to the cache.

If the object can be written, then the cache calls contp back with the event INK_EVENT_CACHE_OPEN_WRITE. In this case, the cache also passes contp a cache vconnection in the void *edata argument; contp can then initiate a write operation on that vconnection using INKVConnWrite. The object is not committed to cache until the vconnection is closed.

If the object cannot be written, then the cache calls contp back with the event INK_EVENT_CACHE_OPEN_WRITE_FAILED. This can happen, for example, if there is another object with the same key being written to the cache. An error code is passed in the void *edata argument of contp. The error code can be:

  • INK_CACHE_ERROR_NOT_READY: trying to access to the cache before it's initialized.

  • INK_CACHE_ERROR_DOC_BUSY: trying to write a document while another continuation is writing or reading it.

  • Any other value: unknown write failure.

The user (contp) has the option to cancel the action returned by INKCacheWrite.

The actual data is written/read to the cache through the cache vconnection. When the cache calls the user back with OPEN_READ or OPEN_WRITE, it passes a INKVConn to the user. The user uses this vconnection for any data transfer. When all data has been transferred, the user must do a INKVConnClose. In case of any errors, the user must do an INKVConnAbort(contp, 0).

[Note] Note

Reentrant calls are possible; in other words, the cache can call back the user (contp) in the same call.

INKCacheWrite does not overwrite content already stored in the cache under the same cache key. If you try to do so, then the cache returns INK_EVENT_CACHE_OPEN_WRITE_FAILED. To overwrite content, first call INKCacheRemove to remove the content and then call INKCacheWrite.

Returns

An INKAction object if successful.

INK_ERROR_PTR if an argument is incorrect or the API fails.