<html>
<head>
<meta name="viewport" content="width=device-width" />
<base href="https://wiki.asterisk.org/wiki" />
<style type="text/css">
body, #email-content, #email-content-inner { font-family: Arial,FreeSans,Helvetica,sans-serif; }
body, p, blockquote, pre, code, td, th, li, dt, dd { font-size: 13px; }
small { font-size: 11px; }
body { width:100% !important; -webkit-font-smoothing: antialiased; }
body,
#email-wrapper { background-color: #f0f0f0; }
#email-wrapper-inner { padding: 20px; text-align: center; }
#email-content-inner { background-color: #fff; border: 1px solid #bbb; color: $menuTxtColour; padding:20px; text-align:left; }
#email-wrapper-inner > table { width: 100%; }
#email-wrapper-inner.thin > table { margin: 0 auto; width: 50%; }
#email-footer { padding: 0 16px 32px 16px; margin: 0; }
.email-indent { margin: 8px 0 16px 0; }
.email-comment { margin: 0 0 0 56px; }
.email-comment.removed { background-color: #ffe7e7; border: 1px solid #df9898; padding: 0 8px;}
#email-title-avatar { text-align: left; vertical-align: top; width: 48px; padding-right: 8px; }
#email-title-flavor { margin: 0; padding: 0 0 4px 0; }
#email-title-heading { font-size: 16px; line-height: 20px; min-height: 20px; margin: 0; padding: 0; }
#email-title .icon { border: 0; padding: 0 5px 0 0; text-align: left; vertical-align: middle; }
#email-actions { border-top: 1px solid #bbb; color: #505050; margin: 8px 0 0 0; padding: 0; }
#email-actions td { padding-top: 8px; }
#email-actions .left { max-width: 45%; text-align: left; }
#email-actions .right { text-align: right; }
.email-reply-divider { border-top: 1px solid #bbb; color: #505050; margin: 32px 0 8px 0; padding: 8px 0; }
.email-section-title { border-bottom: 1px solid #bbb; margin: 8px 0; padding: 8px 0 0 0; }
.email-metadata { color: #505050; }
a { color: #326ca6; text-decoration: none; }
a:hover { color: #336ca6; text-decoration: underline; }
a:active {color: #326ca6; }
a.email-footer-link { color: #505050; font-size: 11px; }
.email-item-list { list-style: none; margin: 4px 0; padding-left: 0; }
.email-item-list li { list-style: none; margin: 0; padding: 4px 0; }
.email-list-divider { color: #505050; padding: 0 0.35em; }
.email-operation-icon { padding-right: 5px; }
.avatar { -ms-interpolation-mode: bicubic; border-radius: 3px;}
.avatar-link { margin: 2px; }
.tableview th { border-bottom: 1px solid #69C; font-weight: bold; text-align: left; }
.tableview td { border-bottom: 1px solid #bbbbbb; text-align: left; padding: 4px 16px 4px 0; }
.aui-message { margin: 1em 0; padding: 8px; }
.aui-message.info { background-color: #e0f0ff; border: 1px solid #9eb6d4; }
.aui-message.success { background-color: #ddfade; border: 1px solid #93c49f; }
.aui-message.error,
.aui-message.removed { background-color: #ffe7e7; border: 1px solid #df9898; color: #000; }
.call-to-action-table { margin: 10px 1px 1px 1px;}
.call-to-cancel-container, .call-to-action-container { padding: 5px 20px; }
.call-to-cancel-container { border: 1px solid #aaa; background-color: #eee; border-radius: 3px; }
.call-to-cancel-container a.call-to-cancel-button { background-color: #eee; font-size: 14px; line-height: 1; padding: 0; margin: 0; color: #666; font-family: sans-serif;}
.call-to-action-container { border: 1px solid #486582; background-color: #3068A2; border-radius: 3px; padding: 4px 10px; }
.call-to-action-container a.call-to-action-button { background-color: #3068A2; font-size: 14px; line-height: 1; padding: 0; margin: 0; color: #fff; font-weight: bold; font-family: sans-serif; }
/** The span around the inline task checkbox image */
.diff-inline-task-overlay {
display: inline-block;
text-align: center;
height: 1.5em;
padding: 5px 0px 1px 5px;
margin-right: 5px;
/** Unfortunately, the negative margin-left is stripped out in gmail */
margin-left: -5px;
}
@media handheld, only screen and (max-device-width: 480px) {
div, a, p, td, th, li, dt, dd { -webkit-text-size-adjust: auto; }
small, small a { -webkit-text-size-adjust: 90%; }
td[id=email-wrapper-inner] { padding: 2px !important; }
td[id=email-content-inner] { padding: 8px !important; }
td[id="email-wrapper-inner"][class="thin"] > table { text-align: left !important; width: 100% !important; }
td[id=email-footer] { padding: 8px 12px !important; }
div[class=email-indent] { margin: 8px 0px !important; }
div[class=email-comment] { margin: 0 !important; }
p[id=email-title-flavor] a { display: block; } /* puts the username and the action on separate lines */
p[id=email-permalink] { padding: 4px 0 0 0 !important; }
table[id=email-actions] td { padding-top: 0 !important; }
table[id=email-actions] td.right { text-align: right !important; }
table[id=email-actions] .email-list-item { display: block; margin: 1em 0 !important; word-wrap: normal !important; }
span[class=email-list-divider] { display: none; }
}
</style>
</head>
<body style="font-family: Arial, FreeSans, Helvetica, sans-serif; font-size: 13px; width: 100%; -webkit-font-smoothing: antialiased; background-color: #f0f0f0">
<table id="email-wrapper" width="100%" cellspacing="0" cellpadding="0" border="0" style="background-color: #f0f0f0">
<tbody>
<tr valign="middle">
<td id="email-wrapper-inner" style="font-size: 13px; padding: 20px; text-align: center">
<table id="email-content" cellspacing="0" cellpadding="0" border="0" style="font-family: Arial, FreeSans, Helvetica, sans-serif; width: 100%">
<tbody>
<tr valign="top">
<td id="email-content-inner" align="left" style="font-family: Arial, FreeSans, Helvetica, sans-serif; font-size: 13px; background-color: #fff; border: 1px solid #bbb; padding: 20px; text-align: left">
<table id="email-title" cellpadding="0" cellspacing="0" border="0" width="100%">
<tbody>
<tr>
<td id="email-title-avatar" rowspan="2" style="font-size: 13px; text-align: left; vertical-align: top; width: 48px; padding-right: 8px"> <img class="avatar" src="cid:avatar_fccb52e35e6902eb9eda9f0f10aaca56" border="0" height="48" width="48" style="-ms-interpolation-mode: bicubic; border-radius: 3px" /> </td>
<td valign="top" style="font-size: 13px">
<div id="email-title-flavor" class="email-metadata" style="margin: 0; padding: 0 0 4px 0; color: #505050">
<a href=" https://wiki.asterisk.org/wiki/display/~rmudgett " style="color:#326ca6;text-decoration:none;; color: #326ca6; text-decoration: none">Richard Mudgett</a> created a page:
</div> </td>
</tr>
<tr>
<td valign="top" style="font-size: 13px"> <h2 id="email-title-heading" style="font-size: 16px; line-height: 20px; min-height: 20px; margin: 0; padding: 0"> <a href="https://wiki.asterisk.org/wiki/pages/viewpage.action?pageId=25919686" style="color: #326ca6; text-decoration: none"> <img class="icon" src="cid:page-icon" alt="" style="border: 0; padding: 0 5px 0 0; text-align: left; vertical-align: middle" /> <strong style="font-size:16px;line-height:20px;vertical-align:top;">Templates for ao2 hash, sort, and callback functions.</strong> </a> </h2> </td>
</tr>
</tbody>
</table>
<div class="email-indent" style="margin: 8px 0 16px 0">
<div class="email-page">
<p style="font-size: 13px">The container comparison functions historically only had the following flag to optimize a container search: OBJ_POINTER. Asterisk 11 added the additional flag to simplify places that requested code searches: OBJ_KEY. Now with the ability to have sorted containers a third flag is available: OBJ_PARTIAL_KEY. These three flags cannot be used at the same time.</p>
<p style="font-size: 13px"> </p>
<p style="font-size: 13px">There is a lot of historical code that does simple bit tests and sets. This code needs to be changed to take into account the fact that there are new search flags and must guard against their use if they are not supported by the container. Most of the adjustments are needed by the ao2_hash_fn and ao2_callback_fn functions of the containers.</p>
<p style="font-size: 13px"> </p>
<p style="font-size: 13px">The following code templates should be used to implement the container callback functions. The templates use string keys but can be adapted for different types of keys.</p>
<p style="font-size: 13px"> </p>
<pre style="font-size: 13px">int ao2_hash_fn(const void *obj, int flags)</pre>
<pre style="font-size: 13px">{</pre>
<pre style="font-size: 13px"> const struct my_object *object;</pre>
<pre style="font-size: 13px"> const char *key;</pre>
<pre style="font-size: 13px"> </pre>
<pre style="font-size: 13px"> switch (flags & (OBJ_POINTER | OBJ_KEY | OBJ_PARTIAL_KEY)) {</pre>
<pre style="font-size: 13px"> case OBJ_KEY:</pre>
<pre style="font-size: 13px"> key = obj;</pre>
<pre style="font-size: 13px"> return ast_str_hash(key);</pre>
<pre style="font-size: 13px"> case OBJ_POINTER:</pre>
<pre style="font-size: 13px"> object = obj;</pre>
<pre style="font-size: 13px"> return ast_str_hash(my_object->key);</pre>
<pre style="font-size: 13px"> default:</pre>
<pre style="font-size: 13px"> /* Hash can only work on something with a full key. */</pre>
<pre style="font-size: 13px"> ast_assert(0);</pre>
<pre style="font-size: 13px"> return 0;</pre>
<pre style="font-size: 13px"> }</pre>
<pre style="font-size: 13px">}</pre>
<pre style="font-size: 13px">
<br /> </pre>
<pre style="font-size: 13px">int ao2_sort_fn(const void *obj_left, const void *obj_right, int flags)</pre>
<pre style="font-size: 13px">{</pre>
<pre style="font-size: 13px"> const struct my_object *object_left = obj_left;</pre>
<pre style="font-size: 13px"> const struct my_object *object_right = obj_right;</pre>
<pre style="font-size: 13px"> const char *right_key = obj_right;</pre>
<pre style="font-size: 13px"> int cmp;</pre>
<pre style="font-size: 13px"> </pre>
<pre style="font-size: 13px"> switch (flags & (OBJ_POINTER | OBJ_KEY | OBJ_PARTIAL_KEY)) {</pre>
<pre style="font-size: 13px"> case OBJ_POINTER:</pre>
<pre style="font-size: 13px"> right_key = object_right->username;</pre>
<pre style="font-size: 13px"> /* Fall through */</pre>
<pre style="font-size: 13px"> case OBJ_KEY:</pre>
<pre style="font-size: 13px"> cmp = strcmp(object_left->username, right_key);</pre>
<pre style="font-size: 13px"> break;</pre>
<pre style="font-size: 13px"> case OBJ_PARTIAL_KEY:</pre>
<pre style="font-size: 13px"> /*</pre>
<pre style="font-size: 13px"> * We could also use a partial key struct containing a length</pre>
<pre style="font-size: 13px"> * so strlen() does not get called for every comparison instead.</pre>
<pre style="font-size: 13px"> */</pre>
<pre style="font-size: 13px"> cmp = strncmp(object_left->username, right_key, strlen(right_key));</pre>
<pre style="font-size: 13px"> break;</pre>
<pre style="font-size: 13px"> default:</pre>
<pre style="font-size: 13px"> /* Sort can only work on something with a full or partial key. */</pre>
<pre style="font-size: 13px"> ast_assert(0);</pre>
<pre style="font-size: 13px"> cmp = 0;</pre>
<pre style="font-size: 13px"> break;</pre>
<pre style="font-size: 13px"> }</pre>
<pre style="font-size: 13px"> return cmp;</pre>
<pre style="font-size: 13px">}</pre>
<pre style="font-size: 13px">
<br /> </pre>
<p style="font-size: 13px">The sort/hash comparison functions act as a filter before the ao2_callback_fn function is called. Every object is matched first by the sort/hash functions. This callback just adds additional discrimination between otherwise equal matches. For most sorted container searches you won't need a special callback and can use the default to match everything by passing NULL for this function.</p>
<p style="font-size: 13px"> </p>
<p style="font-size: 13px">However, with OBJ_CONTINUE, the sort/hash functions are only used to find the starting point in a container traversal of all objects.</p>
<p style="font-size: 13px"> </p>
<p style="font-size: 13px">This function should not return CMP_STOP unless you never want a container search to find multiple objects with the OBJ_MULTIPLE flag.</p>
<p style="font-size: 13px"> </p>
<pre style="font-size: 13px">int ao2_callback_fn_sorted(void *obj, void *arg, int flags)</pre>
<pre style="font-size: 13px">{</pre>
<pre style="font-size: 13px"> return CMP_MATCH;</pre>
<pre style="font-size: 13px">}</pre>
<p style="font-size: 13px"> <br /> </p>
<p style="font-size: 13px"> </p>
<p style="font-size: 13px">Unsorted containers must do more work selecting objects since traversals will either traverse the whole container or one hash bucket.</p>
<p style="font-size: 13px"> </p>
<pre style="font-size: 13px">int ao2_callback_fn_unsorted(void *obj, void *arg, int flags)</pre>
<pre style="font-size: 13px">{</pre>
<pre style="font-size: 13px"> const struct my_object *object_left = obj;</pre>
<pre style="font-size: 13px"> const struct my_object *object_right = arg;</pre>
<pre style="font-size: 13px"> const char *right_key = arg;</pre>
<pre style="font-size: 13px"> int cmp;</pre>
<pre style="font-size: 13px"> </pre>
<pre style="font-size: 13px"> switch (flags & (OBJ_POINTER | OBJ_KEY | OBJ_PARTIAL_KEY)) {</pre>
<pre style="font-size: 13px"> case OBJ_POINTER:</pre>
<pre style="font-size: 13px"> right_key = object_right->username;</pre>
<pre style="font-size: 13px"> /* Fall through */</pre>
<pre style="font-size: 13px"> case OBJ_KEY:</pre>
<pre style="font-size: 13px"> cmp = strcmp(object_left->username, right_key);</pre>
<pre style="font-size: 13px"> break;</pre>
<pre style="font-size: 13px"> case OBJ_PARTIAL_KEY:</pre>
<pre style="font-size: 13px"> /*</pre>
<pre style="font-size: 13px"> * We could also use a partial key struct containing a length</pre>
<pre style="font-size: 13px"> * so strlen() does not get called for every comparison instead.</pre>
<pre style="font-size: 13px"> */</pre>
<pre style="font-size: 13px"> cmp = strncmp(object_left->username, right_key, strlen(right_key));</pre>
<pre style="font-size: 13px"> break;</pre>
<pre style="font-size: 13px"> default:</pre>
<pre style="font-size: 13px"> /*</pre>
<pre style="font-size: 13px"> * What arg points to is specific to this traversal callback</pre>
<pre style="font-size: 13px"> * and has no special meaning to astobj2.</pre>
<pre style="font-size: 13px"> */</pre>
<pre style="font-size: 13px"> cmp = 0;</pre>
<pre style="font-size: 13px"> break;</pre>
<pre style="font-size: 13px"> }</pre>
<pre style="font-size: 13px"> if (cmp) {</pre>
<pre style="font-size: 13px"> return 0;</pre>
<pre style="font-size: 13px"> }</pre>
<pre style="font-size: 13px"> </pre>
<pre style="font-size: 13px"> /*</pre>
<pre style="font-size: 13px"> * At this point the traversal callback is identical to a sorted</pre>
<pre style="font-size: 13px"> * container.</pre>
<pre style="font-size: 13px"> */</pre>
<pre style="font-size: 13px"> return ao2_callback_fn_sorted(obj, arg, flags);</pre>
<pre style="font-size: 13px">}</pre>
<pre style="font-size: 13px">
<br /> </pre>
<p style="font-size: 13px"> </p>
<p style="font-size: 13px">An additional improvement to astobj2 is to formally make these flags an enumerated flag field like the OBJ_ORDER_xxx field so the names can indicate they are related to each other. The following is the proposed new names:</p>
<p style="font-size: 13px"> </p>
<p style="font-size: 13px">* OBJ_SEARCH_MASK - Bit mask to isolate the bit field in the flags.</p>
<p style="font-size: 13px">* OBJ_SEARCH_NONE - The arg pointer has no meaning to the astobj2 code.</p>
<p style="font-size: 13px">* OBJ_SEARCH_OBJECT - The arg pointer points to an object that can be stored in the container.</p>
<p style="font-size: 13px">* OBJ_SEARCH_KEY - The arg pointer points to a key value used by the container.</p>
<p style="font-size: 13px">* OBJ_SEARCH_PARTIAL_KEY - The arg pointer points to a partial key value used by the container.</p>
<p style="font-size: 13px"> </p>
<p style="font-size: 13px">OBJ_POINTER will be defined as OBJ_SEARCH_OBJECT</p>
<p style="font-size: 13px">OBJ_KEY will be defined as OBJ_SEARCH_KEY</p>
<p style="font-size: 13px">OBJ_PARTIAL_KEY will be defined as OBJ_SEARCH_PARTIAL_KEY</p>
<p style="font-size: 13px"> </p>
<p style="font-size: 13px"> </p>
</div>
</div>
<table id="email-actions" class="email-metadata" cellspacing="0" cellpadding="0" border="0" width="100%" style="border-top: 1px solid #bbb; color: #505050; margin: 8px 0 0 0; padding: 0; color: #505050">
<tbody>
<tr>
<td class="left" valign="top" style="font-size: 13px; padding-top: 8px; max-width: 45%; text-align: left"> <span class="email-list-item"><a href="https://wiki.asterisk.org/wiki/pages/viewpage.action?pageId=25919686" style="color: #326ca6; text-decoration: none">View Online</a> </span> <span class="email-list-divider" style="color: #505050; padding: 0 0.350em">·</span> <span class="email-list-item"><a href="https://wiki.asterisk.org/wiki/plugins/likes/like.action?contentId=25919686" style="color: #326ca6; text-decoration: none">Like</a> </span> <span class="email-list-divider" style="color: #505050; padding: 0 0.350em">·</span> <span class="email-list-item"><a href="https://wiki.asterisk.org/wiki/pages/viewpage.action?pageId=25919686&showComments=true&showCommentArea=true#addcomment" style="color: #326ca6; text-decoration: none">Add Comment</a> </span> </td>
<td class="right" width="50%" valign="top" style="font-size: 13px; padding-top: 8px; text-align: right"> <span class="email-list-item"><a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=AST" style="color: #326ca6; text-decoration: none">Stop watching space</a> </span> <span class="email-list-divider" style="color: #505050; padding: 0 0.350em">·</span> <span class="email-list-item"><a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action" style="color: #326ca6; text-decoration: none">Manage Notifications</a> </span> </td>
</tr>
</tbody>
</table> </td>
</tr>
</tbody>
</table> </td>
</tr>
<tr>
<td id="email-footer" align="center" style="font-size: 13px; padding: 0 16px 32px 16px; margin: 0"> <small style="font-size: 11px"> This message was sent by <a class="email-footer-link" style="color:#505050;font-size:11px;text-decoration:none;; color: #326ca6; text-decoration: none; color: #505050; font-size: 11px" href="http://www.atlassian.com/software/confluence">Atlassian Confluence</a> 5.0.3, <a class="email-footer-link" style="color:#505050;font-size:11px;text-decoration:none;; color: #326ca6; text-decoration: none; color: #505050; font-size: 11px" href="http://www.atlassian.com/software/confluence/overview/team-collaboration-software?utm_source=email-footer">Team Collaboration Software</a> </small> </td>
</tr>
</tbody>
</table>
</body>
</html>