[
https://issues.apache.org/jira/browse/TS-4518?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15351355#comment-15351355
]
ASF GitHub Bot commented on TS-4518:
------------------------------------
Github user jpeach commented on a diff in the pull request:
https://github.com/apache/trafficserver/pull/736#discussion_r68608958
--- Diff: doc/developer-guide/api/functions/TSUuidCreate.en.rst ---
@@ -0,0 +1,138 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+.. include:: ../../../common.defs
+
+.. default-domain:: c
+
+TSUuidCreate
+************
+
+Traffic Server UUID construction APIs.
+
+Synopsis
+========
+
+`#include <ts/ts.h>`
+
+.. function:: TSUuid TSUuidCreate(void);
+.. function:: TSReturnCode TSUuidInitialize(TSUuid uuid, TSUuidVersion v);
+.. function:: void TSUuidDestroy(TSUuid uuid);
+.. function:: TSReturnCode TSUuidCopy(TSUuid dest, const TSUuid src);
+.. function:: const char *TSUuidStringGet(const TSUuid uuid);
+.. function:: TSUuidVersion TSUuidVersionGet(const TSUuid uuid);
+.. function:: TSReturnCode TSUuidStringParse(TSUuid uuid, const char
*uuid_str);
+.. function:: const TSUuid TSProcessUuidGet(void);
+
+Description
+===========
+
+These APIs are used to create, manage, and use UUIDs in a plugin,
implementing
+part of RFC 4122. Currently, only the V4 variant of the specifications is
+implemented. In addition, an internal, process unique UUID is provided,
which
+can be used to uniquely identifying the running Traffic Server process.
+
+:func:`TSUuidCreate` creates a new :type:`TSUuid` object, which is returned
+and can be used by the other APIs. Similarly, a read-only global process
UUID
+is returned from the function :func:`TSProcessUuidGet`. You must not
attempt
+to modify any data as returned by either of these functions.
+
+:func:`TSUuidInitialize` initializes a :type:`TSUuid` object, using the
+algorithm defined for the specified version. Note that only the V4
variants is
+currently supported. You can call :func:`TSUuidInitialize` repeatedly,
which
+each generates a new UUID, but this will overwrite any existing UUID data
in
+the object. This also implies that any strings retrieved using
+:func:`TSUuidStringGet` are also modified accordingly.
+
+:func:`TSUuidDestroy` destroys (releases) an :type:`TSUuid` object, and
frees
+all memory associated with this object. This includes any strings as
returned
+by e.g. :func:`TSUuidStringGet`.
+
+:func:`TSUuidCopy` copies one :type:`TSUuid` to another, making an exact
+duplicate. Note that both the source and the destination UUIDs must be
created
+appropriately, and should not have been previously destroyed.
+
+:func:`TSUuidVersionGet` returns the version number for the
+:type:`TSUuid`. This will work properly for any RFC 4122 initialized UUID
+object, e.g. if you parse a string with :func:`TSUuidStringParse` this will
+return the correct variant ID.
+
+:func:`TSUuidStringGet` returns a pointer to the internal string
+representation of the :type:`TSUuid` object. It's important to know that
there
+is no transfer of ownership of this string. If you need a copy of it, you
are
+responsible of doing so yourself. In particular, using a string as
returned by
+:func:`TSUuidStringGet` **after** you have called :func:`TSUuidDestroy` on
the
+corresponding :type:`TSUuid` object is a serious error. The UUID object
does
+not do any sort of reference counting on the string, and you must
absolutely
+not free the memory as returned by this API.
+
+Finally, :func:`TSUuidStringParse` can be used to convert an existing
+:type:`TSUuid` string to a Traffic Server UUID object. This will only
succeed
+if the :type:`TSUuid` string is a proper *RFC 4122* UUID. The
:type:`TSUuid`
+argument passed to this function must be a properly :func:`TSUuidCreate`
+object, but it does not need to be previously initialized.
+
+Return Values
+=============
+
+The :type:`TSUuid` type is an opaque pointer to an internal representation
of
+the UUID object. Several of the functions returns a normal Traffic Server
+return status code, :type:`TSReturnCode`. You should verify the success of
+those APIs, of course.
+
+The :func:`TSUuidStringGet` function will return ``NULL`` if the
:type:`TSUuid`
+object is not properly inititialized. Likewise, :func:`TSUuidVersionGet`
would
+then return ``TS_UUID_UNDEFINED``.
+
+The :func:`TSUuidDestroy` function can not fail, and does not have a return
+value, but you are of course responsible for providing a valid
:type:`TSUuid`
+object.
+
+Examples
+========
+
+This example uses :func:`TSDebugSpecific` to log a message when a specific
+debugging flag is enabled::
+
--- End diff --
``.. code-block: c``
Since this is a code snippet
> UUID and HttpSM ID APIs and Machine support for a process UUID
> --------------------------------------------------------------
>
> Key: TS-4518
> URL: https://issues.apache.org/jira/browse/TS-4518
> Project: Traffic Server
> Issue Type: New Feature
> Components: Core, TS API
> Reporter: Leif Hedstrom
> Assignee: Leif Hedstrom
> Fix For: 7.0.0
>
>
> As was discussed on https://github.com/apache/trafficserver/pull/199, I've
> started the work to generalize this, and breaking it up in various parts.
> This first Jira is about adding four things:
> 1) An internal process UUID, which goes into Machine. It's accessible from
> the core.
> 2) An API to get this Machine UUID.
> 3) A set of generic UUID APIs, to do things like stringification, Copy() etc.
> 4) A very simple API that exposes the HttpSM's sequences number (sm_id).
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
