lib/base/heimbase.c

   1 /*
   2  * Copyright (c) 2010 Kungliga Tekniska Högskolan
   3  * (Royal Institute of Technology, Stockholm, Sweden).
   4  * All rights reserved.
   5  *
   6  * Portions Copyright (c) 2010 Apple Inc. All rights reserved.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions
  10  * are met:
  11  *
  12  * 1. Redistributions of source code must retain the above copyright
  13  *    notice, this list of conditions and the following disclaimer.
  14  *
  15  * 2. Redistributions in binary form must reproduce the above copyright
  16  *    notice, this list of conditions and the following disclaimer in the
  17  *    documentation and/or other materials provided with the distribution.
  18  *
  19  * 3. Neither the name of the Institute nor the names of its contributors
  20  *    may be used to endorse or promote products derived from this software
  21  *    without specific prior written permission.
  22  *
  23  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  24  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  27  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33  * SUCH DAMAGE.
  34  */
  35
  36 #include "baselocl.h"
  37 #include <syslog.h>
  38
  39 static heim_base_atomic_type tidglobal = HEIM_TID_USER;
  40
  41 struct heim_base {
  42     heim_type_t isa;
  43     heim_base_atomic_type ref_cnt;
  44     HEIM_TAILQ_ENTRY(heim_base) autorel;
  45     heim_auto_release_t autorelpool;
  46     uintptr_t isaextra[3];
  47 };
  48
  49 /* specialized version of base */
  50 struct heim_base_mem {
  51     heim_type_t isa;
  52     heim_base_atomic_type ref_cnt;
  53     HEIM_TAILQ_ENTRY(heim_base) autorel;
  54     heim_auto_release_t autorelpool;
  55     const char *name;
  56     void (*dealloc)(void *);
  57     uintptr_t isaextra[1];
  58 };
  59
  60 #define PTR2BASE(ptr) (((struct heim_base *)ptr) - 1)
  61 #define BASE2PTR(ptr) ((void *)(((struct heim_base *)ptr) + 1))
  62
  63 #ifdef HEIM_BASE_NEED_ATOMIC_MUTEX
  64 HEIMDAL_MUTEX _heim_base_mutex = HEIMDAL_MUTEX_INITIALIZER;
  65 #endif
  66
  67 /*
  68  * Auto release structure
  69  */
  70
  71 struct heim_auto_release {
  72     HEIM_TAILQ_HEAD(, heim_base) pool;
  73     HEIMDAL_MUTEX pool_mutex;
  74     struct heim_auto_release *parent;
  75 };
  76
  77
  78 /**
  79  * Retain object (i.e., take a reference)
  80  *
  81  * @param object to be released, NULL is ok
  82  *
  83  * @return the same object as passed in
  84  */
  85
  86 void *
  87 heim_retain(void *ptr)
  88 {
  89     struct heim_base *p = PTR2BASE(ptr);
  90
  91     if (ptr == NULL || heim_base_is_tagged(ptr))
  92         return ptr;
  93
  94     if (p->ref_cnt == heim_base_atomic_max)
  95         return ptr;
  96
  97     if ((heim_base_atomic_inc(&p->ref_cnt) - 1) == 0)
  98         heim_abort("resurection");
  99     return ptr;
 100 }
 101
 102 /**
 103  * Release object, free if reference count reaches zero
 104  *
 105  * @param object to be released
 106  */
 107
 108 void
 109 heim_release(void *ptr)
 110 {
 111     heim_base_atomic_type old;
 112     struct heim_base *p = PTR2BASE(ptr);
 113
 114     if (ptr == NULL || heim_base_is_tagged(ptr))
 115         return;
 116
 117     if (p->ref_cnt == heim_base_atomic_max)
 118         return;
 119
 120     old = heim_base_atomic_dec(&p->ref_cnt) + 1;
 121
 122     if (old > 1)
 123         return;
 124
 125     if (old == 1) {
 126         heim_auto_release_t ar = p->autorelpool;
 127         /* remove from autorel pool list */
 128         if (ar) {
 129             p->autorelpool = NULL;
 130             HEIMDAL_MUTEX_lock(&ar->pool_mutex);
 131             HEIM_TAILQ_REMOVE(&ar->pool, p, autorel);
 132             HEIMDAL_MUTEX_unlock(&ar->pool_mutex);
 133         }
 134         if (p->isa->dealloc)
 135             p->isa->dealloc(ptr);
 136         free(p);
 137     } else
 138         heim_abort("over release");
 139 }
 140
 141 /**
 142  * If used require wrapped in autorelease pool
 143  */
 144
 145 heim_string_t
 146 heim_description(heim_object_t ptr)
 147 {
 148     struct heim_base *p = PTR2BASE(ptr);
 149     if (p->isa->desc == NULL)
 150         return heim_auto_release(heim_string_ref_create(p->isa->name, NULL));
 151     return heim_auto_release(p->isa->desc(ptr));
 152 }
 153
 154
 155 void
 156 _heim_make_permanent(heim_object_t ptr)
 157 {
 158     struct heim_base *p = PTR2BASE(ptr);
 159     p->ref_cnt = heim_base_atomic_max;
 160 }
 161
 162
 163 static heim_type_t tagged_isa[9] = {
 164     &_heim_number_object,
 165     &_heim_null_object,
 166     &_heim_bool_object,
 167
 168     NULL,
 169     NULL,
 170     NULL,
 171
 172     NULL,
 173     NULL,
 174     NULL
 175 };
 176
 177 heim_type_t
 178 _heim_get_isa(heim_object_t ptr)
 179 {
 180     struct heim_base *p;
 181     if (heim_base_is_tagged(ptr)) {
 182         if (heim_base_is_tagged_object(ptr))
 183             return tagged_isa[heim_base_tagged_object_tid(ptr)];
 184         heim_abort("not a supported tagged type");
 185     }
 186     p = PTR2BASE(ptr);
 187     return p->isa;
 188 }
 189
 190 /**
 191  * Get type ID of object
 192  *
 193  * @param object object to get type id of
 194  *
 195  * @return type id of object
 196  */
 197
 198 heim_tid_t
 199 heim_get_tid(heim_object_t ptr)
 200 {
 201     heim_type_t isa = _heim_get_isa(ptr);
 202     return isa->tid;
 203 }
 204
 205 /**
 206  * Get hash value of object
 207  *
 208  * @param object object to get hash value for
 209  *
 210  * @return a hash value
 211  */
 212
 213 unsigned long
 214 heim_get_hash(heim_object_t ptr)
 215 {
 216     heim_type_t isa = _heim_get_isa(ptr);
 217     if (isa->hash)
 218         return isa->hash(ptr);
 219     return (unsigned long)ptr;
 220 }
 221
 222 /**
 223  * Compare two objects, returns 0 if equal, can use used for qsort()
 224  * and friends.
 225  *
 226  * @param a first object to compare
 227  * @param b first object to compare
 228  *
 229  * @return 0 if objects are equal
 230  */
 231
 232 int
 233 heim_cmp(heim_object_t a, heim_object_t b)
 234 {
 235     heim_tid_t ta, tb;
 236     heim_type_t isa;
 237
 238     ta = heim_get_tid(a);
 239     tb = heim_get_tid(b);
 240
 241     if (ta != tb)
 242         return ta - tb;
 243
 244     isa = _heim_get_isa(a);
 245
 246     if (isa->cmp)
 247         return isa->cmp(a, b);
 248
 249     return (uintptr_t)a - (uintptr_t)b;
 250 }
 251
 252 /*
 253  * Private - allocates an memory object
 254  */
 255
 256 static void
 257 memory_dealloc(void *ptr)
 258 {
 259     struct heim_base_mem *p = (struct heim_base_mem *)PTR2BASE(ptr);
 260     if (p->dealloc)
 261         p->dealloc(ptr);
 262 }
 263
 264 struct heim_type_data memory_object = {
 265     HEIM_TID_MEMORY,
 266     "memory-object",
 267     NULL,
 268     memory_dealloc,
 269     NULL,
 270     NULL,
 271     NULL,
 272     NULL
 273 };
 274
 275 /**
 276  * Allocate memory for an object of anonymous type
 277  *
 278  * @param size size of object to be allocated
 279  * @param name name of ad-hoc type
 280  * @param dealloc destructor function
 281  *
 282  * Objects allocated with this interface do not serialize.
 283  *
 284  * @return allocated object
 285  */
 286
 287 void *
 288 heim_alloc(size_t size, const char *name, heim_type_dealloc dealloc)
 289 {
 290     /* XXX use posix_memalign */
 291
 292     struct heim_base_mem *p = calloc(1, size + sizeof(*p));
 293     if (p == NULL)
 294         return NULL;
 295     p->isa = &memory_object;
 296     p->ref_cnt = 1;
 297     p->name = name;
 298     p->dealloc = dealloc;
 299     return BASE2PTR(p);
 300 }
 301
 302 heim_type_t
 303 _heim_create_type(const char *name,
 304                   heim_type_init init,
 305                   heim_type_dealloc dealloc,
 306                   heim_type_copy copy,
 307                   heim_type_cmp cmp,
 308                   heim_type_hash hash,
 309                   heim_type_description desc)
 310 {
 311     heim_type_t type;
 312
 313     type = calloc(1, sizeof(*type));
 314     if (type == NULL)
 315         return NULL;
 316
 317     type->tid = heim_base_atomic_inc(&tidglobal);
 318     type->name = name;
 319     type->init = init;
 320     type->dealloc = dealloc;
 321     type->copy = copy;
 322     type->cmp = cmp;
 323     type->hash = hash;
 324     type->desc = desc;
 325
 326     return type;
 327 }
 328
 329 heim_object_t
 330 _heim_alloc_object(heim_type_t type, size_t size)
 331 {
 332     /* XXX should use posix_memalign */
 333     struct heim_base *p = calloc(1, size + sizeof(*p));
 334     if (p == NULL)
 335         return NULL;
 336     p->isa = type;
 337     p->ref_cnt = 1;
 338
 339     return BASE2PTR(p);
 340 }
 341
 342 void *
 343 _heim_get_isaextra(heim_object_t ptr, size_t idx)
 344 {
 345     struct heim_base *p = (struct heim_base *)PTR2BASE(ptr);
 346
 347     heim_assert(ptr != NULL, "internal error");
 348     if (p->isa == &memory_object)
 349         return NULL;
 350     heim_assert(idx < 3, "invalid private heim_base extra data index");
 351     return &p->isaextra[idx];
 352 }
 353
 354 heim_tid_t
 355 _heim_type_get_tid(heim_type_t type)
 356 {
 357     return type->tid;
 358 }
 359
 360 /**
 361  * Call func once and only once
 362  *
 363  * @param once pointer to a heim_base_once_t
 364  * @param ctx context passed to func
 365  * @param func function to be called
 366  */
 367
 368 void
 369 heim_base_once_f(heim_base_once_t *once, void *ctx, void (*func)(void *))
 370 {
 371 #ifdef HAVE_DISPATCH_DISPATCH_H
 372     dispatch_once_f(once, ctx, func);
 373 #else
 374     static HEIMDAL_MUTEX mutex = HEIMDAL_MUTEX_INITIALIZER;
 375     HEIMDAL_MUTEX_lock(&mutex);
 376     if (*once == 0) {
 377         *once = 1;
 378         HEIMDAL_MUTEX_unlock(&mutex);
 379         func(ctx);
 380         HEIMDAL_MUTEX_lock(&mutex);
 381         *once = 2;
 382         HEIMDAL_MUTEX_unlock(&mutex);
 383     } else if (*once == 2) {
 384         HEIMDAL_MUTEX_unlock(&mutex);
 385     } else {
 386         HEIMDAL_MUTEX_unlock(&mutex);
 387         while (1) {
 388             struct timeval tv = { 0, 1000 };
 389             select(0, NULL, NULL, NULL, &tv);
 390             HEIMDAL_MUTEX_lock(&mutex);
 391             if (*once == 2)
 392                 break;
 393             HEIMDAL_MUTEX_unlock(&mutex);
 394         }
 395         HEIMDAL_MUTEX_unlock(&mutex);
 396     }
 397 #endif
 398 }
 399
 400 /**
 401  * Abort and log the failure (using syslog)
 402  */
 403
 404 void
 405 heim_abort(const char *fmt, ...)
 406 {
 407     va_list ap;
 408     va_start(ap, fmt);
 409     heim_abortv(fmt, ap);
 410     va_end(ap);
 411 }
 412
 413 /**
 414  * Abort and log the failure (using syslog)
 415  */
 416
 417 void
 418 heim_abortv(const char *fmt, va_list ap)
 419 {
 420     static char str[1024];
 421
 422     vsnprintf(str, sizeof(str), fmt, ap);
 423     syslog(LOG_ERR, "heim_abort: %s", str);
 424     abort();
 425 }
 426
 427 /*
 428  *
 429  */
 430
 431 static int ar_created = 0;
 432 static HEIMDAL_thread_key ar_key;
 433
 434 struct ar_tls {
 435     struct heim_auto_release *head;
 436     struct heim_auto_release *current;
 437     HEIMDAL_MUTEX tls_mutex;
 438 };
 439
 440 static void
 441 ar_tls_delete(void *ptr)
 442 {
 443     struct ar_tls *tls = ptr;
 444     if (tls->head)
 445         heim_release(tls->head);
 446     free(tls);
 447 }
 448
 449 static void
 450 init_ar_tls(void *ptr)
 451 {
 452     int ret;
 453     HEIMDAL_key_create(&ar_key, ar_tls_delete, ret);
 454     if (ret == 0)
 455         ar_created = 1;
 456 }
 457
 458 static struct ar_tls *
 459 autorel_tls(void)
 460 {
 461     static heim_base_once_t once = HEIM_BASE_ONCE_INIT;
 462     struct ar_tls *arp;
 463     int ret;
 464
 465     heim_base_once_f(&once, NULL, init_ar_tls);
 466     if (!ar_created)
 467         return NULL;
 468
 469     arp = HEIMDAL_getspecific(ar_key);
 470     if (arp == NULL) {
 471
 472         arp = calloc(1, sizeof(*arp));
 473         if (arp == NULL)
 474             return NULL;
 475         HEIMDAL_setspecific(ar_key, arp, ret);
 476         if (ret) {
 477             free(arp);
 478             return NULL;
 479         }
 480     }
 481     return arp;
 482
 483 }
 484
 485 static void
 486 autorel_dealloc(void *ptr)
 487 {
 488     heim_auto_release_t ar = ptr;
 489     struct ar_tls *tls;
 490
 491     tls = autorel_tls();
 492     if (tls == NULL)
 493         heim_abort("autorelease pool released on thread w/o autorelease inited");
 494
 495     heim_auto_release_drain(ar);
 496
 497     if (!HEIM_TAILQ_EMPTY(&ar->pool))
 498         heim_abort("pool not empty after draining");
 499
 500     HEIMDAL_MUTEX_lock(&tls->tls_mutex);
 501     if (tls->current != ptr)
 502         heim_abort("autorelease not releaseing top pool");
 503
 504     if (tls->current != tls->head)
 505         tls->current = ar->parent;
 506     HEIMDAL_MUTEX_unlock(&tls->tls_mutex);
 507 }
 508
 509 static int
 510 autorel_cmp(void *a, void *b)
 511 {
 512     return (a == b);
 513 }
 514
 515 static unsigned long
 516 autorel_hash(void *ptr)
 517 {
 518     return (unsigned long)ptr;
 519 }
 520
 521
 522 static struct heim_type_data _heim_autorel_object = {
 523     HEIM_TID_AUTORELEASE,
 524     "autorelease-pool",
 525     NULL,
 526     autorel_dealloc,
 527     NULL,
 528     autorel_cmp,
 529     autorel_hash,
 530     NULL
 531 };
 532
 533 /**
 534  * Create thread-specific object auto-release pool
 535  *
 536  * Objects placed on the per-thread auto-release pool (with
 537  * heim_auto_release()) can be released in one fell swoop by calling
 538  * heim_auto_release_drain().
 539  */
 540
 541 heim_auto_release_t
 542 heim_auto_release_create(void)
 543 {
 544     struct ar_tls *tls = autorel_tls();
 545     heim_auto_release_t ar;
 546
 547     if (tls == NULL)
 548         heim_abort("Failed to create/get autorelease head");
 549
 550     ar = _heim_alloc_object(&_heim_autorel_object, sizeof(struct heim_auto_release));
 551     if (ar) {
 552         HEIMDAL_MUTEX_lock(&tls->tls_mutex);
 553         if (tls->head == NULL)
 554             tls->head = ar;
 555         ar->parent = tls->current;
 556         tls->current = ar;
 557         HEIMDAL_MUTEX_unlock(&tls->tls_mutex);
 558     }
 559
 560     return ar;
 561 }
 562
 563 /**
 564  * Place the current object on the thread's auto-release pool
 565  *
 566  * @param ptr object
 567  */
 568
 569 heim_object_t
 570 heim_auto_release(heim_object_t ptr)
 571 {
 572     struct heim_base *p = PTR2BASE(ptr);
 573     struct ar_tls *tls = autorel_tls();
 574     heim_auto_release_t ar;
 575
 576     if (ptr == NULL || heim_base_is_tagged(ptr))
 577         return ptr;
 578
 579     /* drop from old pool */
 580     if ((ar = p->autorelpool) != NULL) {
 581         HEIMDAL_MUTEX_lock(&ar->pool_mutex);
 582         HEIM_TAILQ_REMOVE(&ar->pool, p, autorel);
 583         p->autorelpool = NULL;
 584         HEIMDAL_MUTEX_unlock(&ar->pool_mutex);
 585     }
 586
 587     if (tls == NULL || (ar = tls->current) == NULL)
 588         heim_abort("no auto relase pool in place, would leak");
 589
 590     HEIMDAL_MUTEX_lock(&ar->pool_mutex);
 591     HEIM_TAILQ_INSERT_HEAD(&ar->pool, p, autorel);
 592     p->autorelpool = ar;
 593     HEIMDAL_MUTEX_unlock(&ar->pool_mutex);
 594
 595     return ptr;
 596 }
 597
 598 /**
 599  * Release all objects on the given auto-release pool
 600  */
 601
 602 void
 603 heim_auto_release_drain(heim_auto_release_t autorel)
 604 {
 605     heim_object_t obj;
 606
 607     /* release all elements on the tail queue */
 608
 609     HEIMDAL_MUTEX_lock(&autorel->pool_mutex);
 610     while(!HEIM_TAILQ_EMPTY(&autorel->pool)) {
 611         obj = HEIM_TAILQ_FIRST(&autorel->pool);
 612         HEIMDAL_MUTEX_unlock(&autorel->pool_mutex);
 613         heim_release(BASE2PTR(obj));
 614         HEIMDAL_MUTEX_lock(&autorel->pool_mutex);
 615     }
 616     HEIMDAL_MUTEX_unlock(&autorel->pool_mutex);
 617 }
 618
 619 /*
 620  * Helper for heim_path_vget() and heim_path_delete().  On success
 621  * outputs the node named by the path and the parent node and key
 622  * (useful for heim_path_delete()).
 623  */
 624
 625 static heim_object_t
 626 heim_path_vget2(heim_object_t ptr, heim_object_t *parent, heim_object_t *key,
 627                 heim_error_t *error, va_list ap)
 628 {
 629     heim_object_t path_element;
 630     heim_object_t node, next_node;
 631     heim_tid_t node_type;
 632
 633     *parent = NULL;
 634     *key = NULL;
 635     if (ptr == NULL)
 636         return NULL;
 637
 638     for (node = ptr; node != NULL; ) {
 639         path_element = va_arg(ap, heim_object_t);
 640         if (path_element == NULL) {
 641             *parent = node;
 642             *key = path_element;
 643             return node;
 644         }
 645
 646         node_type = heim_get_tid(node);
 647         switch (node_type) {
 648         case HEIM_TID_ARRAY:
 649         case HEIM_TID_DICT:
 650         case HEIM_TID_DB:
 651             break;
 652         default:
 653             if (node == ptr)
 654                 heim_abort("heim_path_get() only operates on container types");
 655             return NULL;
 656         }
 657
 658         if (node_type == HEIM_TID_DICT) {
 659             next_node = heim_dict_get_value(node, path_element);
 660         } else if (node_type == HEIM_TID_DB) {
 661             next_node = _heim_db_get_value(node, NULL, path_element, NULL);
 662         } else if (node_type == HEIM_TID_ARRAY) {
 663             int idx = -1;
 664
 665             if (heim_get_tid(path_element) == HEIM_TID_NUMBER)
 666                 idx = heim_number_get_int(path_element);
 667             if (idx < 0) {
 668                 if (error)
 669                     *error = heim_error_create(EINVAL,
 670                                                "heim_path_get() path elements "
 671                                                "for array nodes must be "
 672                                                "numeric and positive");
 673                 return NULL;
 674             }
 675             next_node = heim_array_get_value(node, idx);
 676         } else {
 677             if (error)
 678                 *error = heim_error_create(EINVAL,
 679                                            "heim_path_get() node in path "
 680                                            "not a container type");
 681             return NULL;
 682         }
 683         node = next_node;
 684     }
 685     return NULL;
 686 }
 687
 688 /**
 689  * Get a node in a heim_object tree by path
 690  *
 691  * @param ptr tree
 692  * @param error error (output)
 693  * @param ap NULL-terminated va_list of heim_object_ts that form a path
 694  *
 695  * @return object (not retained) if found
 696  *
 697  * @addtogroup heimbase
 698  */
 699
 700 heim_object_t
 701 heim_path_vget(heim_object_t ptr, heim_error_t *error, va_list ap)
 702 {
 703     heim_object_t p, k;
 704
 705     return heim_path_vget2(ptr, &p, &k, error, ap);
 706 }
 707
 708 /**
 709  * Get a node in a tree by path, with retained reference
 710  *
 711  * @param ptr tree
 712  * @param error error (output)
 713  * @param ap NULL-terminated va_list of heim_object_ts that form a path
 714  *
 715  * @return retained object if found
 716  *
 717  * @addtogroup heimbase
 718  */
 719
 720 heim_object_t
 721 heim_path_vcopy(heim_object_t ptr, heim_error_t *error, va_list ap)
 722 {
 723     heim_object_t p, k;
 724
 725     return heim_retain(heim_path_vget2(ptr, &p, &k, error, ap));
 726 }
 727
 728 /**
 729  * Get a node in a tree by path
 730  *
 731  * @param ptr tree
 732  * @param error error (output)
 733  * @param ... NULL-terminated va_list of heim_object_ts that form a path
 734  *
 735  * @return object (not retained) if found
 736  *
 737  * @addtogroup heimbase
 738  */
 739
 740 heim_object_t
 741 heim_path_get(heim_object_t ptr, heim_error_t *error, ...)
 742 {
 743     heim_object_t o;
 744     heim_object_t p, k;
 745     va_list ap;
 746
 747     if (ptr == NULL)
 748         return NULL;
 749
 750     va_start(ap, error);
 751     o = heim_path_vget2(ptr, &p, &k, error, ap);
 752     va_end(ap);
 753     return o;
 754 }
 755
 756 /**
 757  * Get a node in a tree by path, with retained reference
 758  *
 759  * @param ptr tree
 760  * @param error error (output)
 761  * @param ... NULL-terminated va_list of heim_object_ts that form a path
 762  *
 763  * @return retained object if found
 764  *
 765  * @addtogroup heimbase
 766  */
 767
 768 heim_object_t
 769 heim_path_copy(heim_object_t ptr, heim_error_t *error, ...)
 770 {
 771     heim_object_t o;
 772     heim_object_t p, k;
 773     va_list ap;
 774
 775     if (ptr == NULL)
 776         return NULL;
 777
 778     va_start(ap, error);
 779     o = heim_retain(heim_path_vget2(ptr, &p, &k, error, ap));
 780     va_end(ap);
 781     return o;
 782 }
 783
 784 /**
 785  * Create a path in a heim_object_t tree
 786  *
 787  * @param ptr the tree
 788  * @param size the size of the heim_dict_t nodes to be created
 789  * @param leaf leaf node to be added, if any
 790  * @param error error (output)
 791  * @param ap NULL-terminated of path component objects
 792  *
 793  * Create a path of heim_dict_t interior nodes in a given heim_object_t
 794  * tree, as necessary, and set/replace a leaf, if given (if leaf is NULL
 795  * then the leaf is not deleted).
 796  *
 797  * @return 0 on success, else a system error
 798  *
 799  * @addtogroup heimbase
 800  */
 801
 802 int
 803 heim_path_vcreate(heim_object_t ptr, size_t size, heim_object_t leaf,
 804                   heim_error_t *error, va_list ap)
 805 {
 806     heim_object_t path_element = va_arg(ap, heim_object_t);
 807     heim_object_t next_path_element = NULL;
 808     heim_object_t node = ptr;
 809     heim_object_t next_node = NULL;
 810     heim_tid_t node_type;
 811     int ret = 0;
 812
 813     if (ptr == NULL)
 814         heim_abort("heim_path_vcreate() does not create root nodes");
 815
 816     while (path_element != NULL) {
 817         next_path_element = va_arg(ap, heim_object_t);
 818         node_type = heim_get_tid(node);
 819
 820         if (node_type == HEIM_TID_DICT) {
 821             next_node = heim_dict_get_value(node, path_element);
 822         } else if (node_type == HEIM_TID_ARRAY) {
 823             int idx = -1;
 824
 825             if (heim_get_tid(path_element) == HEIM_TID_NUMBER)
 826                 idx = heim_number_get_int(path_element);
 827             if (idx < 0) {
 828                 if (error)
 829                     *error = heim_error_create(EINVAL,
 830                                                "heim_path() path elements for "
 831                                                "array nodes must be numeric "
 832                                                "and positive");
 833                 return EINVAL;
 834             }
 835             if (idx < heim_array_get_length(node))
 836                 next_node = heim_array_get_value(node, idx);
 837             else
 838                 next_node = NULL;
 839         } else if (node_type == HEIM_TID_DB && next_path_element != NULL) {
 840             if (error)
 841                 *error = heim_error_create(EINVAL, "Interior node is a DB");
 842             return EINVAL;
 843         }
 844
 845         if (next_path_element == NULL)
 846             break;
 847
 848         /* Create missing interior node */
 849         if (next_node == NULL) {
 850             next_node = heim_dict_create(size); /* no arrays or DBs, just dicts */
 851             if (next_node == NULL) {
 852                 ret = ENOMEM;
 853                 goto err;
 854             }
 855
 856             if (node_type == HEIM_TID_DICT) {
 857                 ret = heim_dict_set_value(node, path_element, next_node);
 858             } else if (node_type == HEIM_TID_ARRAY &&
 859                 heim_number_get_int(path_element) <= heim_array_get_length(node)) {
 860                 ret = heim_array_insert_value(node,
 861                                               heim_number_get_int(path_element),
 862                                               next_node);
 863             } else {
 864                 ret = EINVAL;
 865                 if (error)
 866                     *error = heim_error_create(ret, "Node in path not a "
 867                                                "container");
 868                 goto err;
 869             }
 870             heim_release(next_node);
 871             if (ret)
 872                 goto err;
 873         }
 874
 875         path_element = next_path_element;
 876         node = next_node;
 877         next_node = NULL;
 878     }
 879
 880     if (path_element == NULL)
 881         goto err;
 882
 883     /* Add the leaf */
 884     if (leaf != NULL) {
 885         if (node_type == HEIM_TID_DICT)
 886             ret = heim_dict_set_value(node, path_element, leaf);
 887         else
 888             ret = heim_array_insert_value(node,
 889                                           heim_number_get_int(path_element),
 890                                           leaf);
 891     }
 892     return 0;
 893
 894 err:
 895     if (error && !*error) {
 896         if (ret == ENOMEM)
 897             *error = heim_error_create_enomem();
 898         else
 899             *error = heim_error_create(ret, "Could not set "
 900                                        "dict value");
 901     }
 902     return ret;
 903 }
 904
 905 /**
 906  * Create a path in a heim_object_t tree
 907  *
 908  * @param ptr the tree
 909  * @param size the size of the heim_dict_t nodes to be created
 910  * @param leaf leaf node to be added, if any
 911  * @param error error (output)
 912  * @param ... NULL-terminated list of path component objects
 913  *
 914  * Create a path of heim_dict_t interior nodes in a given heim_object_t
 915  * tree, as necessary, and set/replace a leaf, if given (if leaf is NULL
 916  * then the leaf is not deleted).
 917  *
 918  * @return 0 on success, else a system error
 919  *
 920  * @addtogroup heimbase
 921  */
 922
 923 int
 924 heim_path_create(heim_object_t ptr, size_t size, heim_object_t leaf,
 925                  heim_error_t *error, ...)
 926 {
 927     va_list ap;
 928     int ret;
 929
 930     va_start(ap, error);
 931     ret = heim_path_vcreate(ptr, size, leaf, error, ap);
 932     va_end(ap);
 933     return ret;
 934 }
 935
 936 /**
 937  * Delete leaf node named by a path in a heim_object_t tree
 938  *
 939  * @param ptr the tree
 940  * @param error error (output)
 941  * @param ap NULL-terminated list of path component objects
 942  *
 943  * @addtogroup heimbase
 944  */
 945
 946 void
 947 heim_path_vdelete(heim_object_t ptr, heim_error_t *error, va_list ap)
 948 {
 949     heim_object_t parent, key, child;
 950
 951     child = heim_path_vget2(ptr, &parent, &key, error, ap);
 952     if (child != NULL) {
 953         if (heim_get_tid(parent) == HEIM_TID_DICT)
 954             heim_dict_delete_key(parent, key);
 955         else if (heim_get_tid(parent) == HEIM_TID_DB)
 956             heim_db_delete_key(parent, NULL, key, error);
 957         else if (heim_get_tid(parent) == HEIM_TID_ARRAY)
 958             heim_array_delete_value(parent, heim_number_get_int(key));
 959         heim_release(child);
 960     }
 961 }
 962
 963 /**
 964  * Delete leaf node named by a path in a heim_object_t tree
 965  *
 966  * @param ptr the tree
 967  * @param error error (output)
 968  * @param ap NULL-terminated list of path component objects
 969  *
 970  * @addtogroup heimbase
 971  */
 972
 973 void
 974 heim_path_delete(heim_object_t ptr, heim_error_t *error, ...)
 975 {
 976     va_list ap;
 977
 978     va_start(ap, error);
 979     heim_path_vdelete(ptr, error, ap);
 980     va_end(ap);
 981     return;
 982 }
 983