Traffic Server Software Developers Kit

When you fetch a component object or create a new object, you get back a handle to the object location. The handle is either an INKMLoc for an object location or char * for a string location. You can manipulate the object through these handles, but when you are finished you need to release the handle to free up system resources.

The general guideline is to release all INKMLoc and string handles you retrieve. The one exception is the string returned by INKUrlStringGet, which must be freed by a call to INKfree.

The handle release functions expect three arguments: the marshal buffer containing the data, the location of the parent object, and the location of the object to be released. The parent location is usually clear from the creation of the INKMLoc or string. For example, if your plugin had the following calls:

url_loc = INKHttpHdrUrlGet (bufp, hdr_loc);
host_string = INKUrlHostGet (bufp, url_loc, &host_length);

then your plugin would have to call:

INKHandleStringRelease (bufp, url_loc, host_string);
INKHandleMLocRelease (bufp, hdr_loc, url_loc);

If an INKMLoc is obtained from a transaction, then it does not have a parent INKMLoc. Use the null INKMLoc constant INK_NULL_MLOC as its parent. For example, if your plugin calls:

INKHttpTxnClientReqGet (txnp, &bufp, &hdr_loc);

then you must release hdr_loc with:

INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);

You need to use INK_NULL_MLOC to release any INKMLoc handles retrieved by the INKHttpTxn*Get functions.

Here’s an example using a new INKMimeHdrField function:

INKHttpTxnServerRespGet( txnp, &resp_bufp, &resp_hdr_loc );
new_field_loc = INKMimeHdrFieldCreate (resp_bufp, resp_hdr_loc);
INKHandleMLocRelease ( resp_bufp, resp_hdr_loc, new_field_loc);
INKHandleMLocRelease ( resp_bufp, INK_NULL_MLOC, resp_hdr_loc);

See the sample plugins for many more examples.

	Tip
	You should release handles before reenabling the HTTP transaction. In other words, call INKHandleMLocRelease or INKHandleStringRelease before INKHttpTxnReenable.