epoch.c

   1 /*
   2  * Copyright (c) 2005, Jon Seymour
   3  *
   4  * For more information about epoch theory on which this module is based,
   5  * refer to http://blackcubes.dyndns.org/epoch/. That web page defines
   6  * terms such as "epoch" and "minimal, non-linear epoch" and provides rationales
   7  * for some of the algorithms used here.
   8  *
   9  */
  10 #include <stdlib.h>
  11
  12 /* Provides arbitrary precision integers required to accurately represent
  13  * fractional mass: */
  14 #include <openssl/bn.h>
  15
  16 #include "cache.h"
  17 #include "commit.h"
  18 #include "epoch.h"
  19
  20 struct fraction {
  21         BIGNUM numerator;
  22         BIGNUM denominator;
  23 };
  24
  25 #define HAS_EXACTLY_ONE_PARENT(n) ((n)->parents && !(n)->parents->next)
  26
  27 static BN_CTX *context = NULL;
  28 static struct fraction *one = NULL;
  29 static struct fraction *zero = NULL;
  30
  31 static BN_CTX *get_BN_CTX()
  32 {
  33         if (!context) {
  34                 context = BN_CTX_new();
  35         }
  36         return context;
  37 }
  38
  39 static struct fraction *new_zero()
  40 {
  41         struct fraction *result = xmalloc(sizeof(*result));
  42         BN_init(&result->numerator);
  43         BN_init(&result->denominator);
  44         BN_zero(&result->numerator);
  45         BN_one(&result->denominator);
  46         return result;
  47 }
  48
  49 static void clear_fraction(struct fraction *fraction)
  50 {
  51         BN_clear(&fraction->numerator);
  52         BN_clear(&fraction->denominator);
  53 }
  54
  55 static struct fraction *divide(struct fraction *result, struct fraction *fraction, int divisor)
  56 {
  57         BIGNUM bn_divisor;
  58
  59         BN_init(&bn_divisor);
  60         BN_set_word(&bn_divisor, divisor);
  61
  62         BN_copy(&result->numerator, &fraction->numerator);
  63         BN_mul(&result->denominator, &fraction->denominator, &bn_divisor, get_BN_CTX());
  64
  65         BN_clear(&bn_divisor);
  66         return result;
  67 }
  68
  69 static struct fraction *init_fraction(struct fraction *fraction)
  70 {
  71         BN_init(&fraction->numerator);
  72         BN_init(&fraction->denominator);
  73         BN_zero(&fraction->numerator);
  74         BN_one(&fraction->denominator);
  75         return fraction;
  76 }
  77
  78 static struct fraction *get_one()
  79 {
  80         if (!one) {
  81                 one = new_zero();
  82                 BN_one(&one->numerator);
  83         }
  84         return one;
  85 }
  86
  87 static struct fraction *get_zero()
  88 {
  89         if (!zero) {
  90                 zero = new_zero();
  91         }
  92         return zero;
  93 }
  94
  95 static struct fraction *copy(struct fraction *to, struct fraction *from)
  96 {
  97         BN_copy(&to->numerator, &from->numerator);
  98         BN_copy(&to->denominator, &from->denominator);
  99         return to;
 100 }
 101
 102 static struct fraction *add(struct fraction *result, struct fraction *left, struct fraction *right)
 103 {
 104         BIGNUM a, b, gcd;
 105
 106         BN_init(&a);
 107         BN_init(&b);
 108         BN_init(&gcd);
 109
 110         BN_mul(&a, &left->numerator, &right->denominator, get_BN_CTX());
 111         BN_mul(&b, &left->denominator, &right->numerator, get_BN_CTX());
 112         BN_mul(&result->denominator, &left->denominator, &right->denominator, get_BN_CTX());
 113         BN_add(&result->numerator, &a, &b);
 114
 115         BN_gcd(&gcd, &result->denominator, &result->numerator, get_BN_CTX());
 116         BN_div(&result->denominator, NULL, &result->denominator, &gcd, get_BN_CTX());
 117         BN_div(&result->numerator, NULL, &result->numerator, &gcd, get_BN_CTX());
 118
 119         BN_clear(&a);
 120         BN_clear(&b);
 121         BN_clear(&gcd);
 122
 123         return result;
 124 }
 125
 126 static int compare(struct fraction *left, struct fraction *right)
 127 {
 128         BIGNUM a, b;
 129         int result;
 130
 131         BN_init(&a);
 132         BN_init(&b);
 133
 134         BN_mul(&a, &left->numerator, &right->denominator, get_BN_CTX());
 135         BN_mul(&b, &left->denominator, &right->numerator, get_BN_CTX());
 136
 137         result = BN_cmp(&a, &b);
 138
 139         BN_clear(&a);
 140         BN_clear(&b);
 141
 142         return result;
 143 }
 144
 145 struct mass_counter {
 146         struct fraction seen;
 147         struct fraction pending;
 148 };
 149
 150 static struct mass_counter *new_mass_counter(struct commit *commit, struct fraction *pending)
 151 {
 152         struct mass_counter *mass_counter = xmalloc(sizeof(*mass_counter));
 153         memset(mass_counter, 0, sizeof(*mass_counter));
 154
 155         init_fraction(&mass_counter->seen);
 156         init_fraction(&mass_counter->pending);
 157
 158         copy(&mass_counter->pending, pending);
 159         copy(&mass_counter->seen, get_zero());
 160
 161         if (commit->object.util) {
 162                 die("multiple attempts to initialize mass counter for %s",
 163                     sha1_to_hex(commit->object.sha1));
 164         }
 165
 166         commit->object.util = mass_counter;
 167
 168         return mass_counter;
 169 }
 170
 171 static void free_mass_counter(struct mass_counter *counter)
 172 {
 173         clear_fraction(&counter->seen);
 174         clear_fraction(&counter->pending);
 175         free(counter);
 176 }
 177
 178 /*
 179  * Finds the base commit of a list of commits.
 180  *
 181  * One property of the commit being searched for is that every commit reachable
 182  * from the base commit is reachable from the commits in the starting list only
 183  * via paths that include the base commit.
 184  *
 185  * This algorithm uses a conservation of mass approach to find the base commit.
 186  *
 187  * We start by injecting one unit of mass into the graph at each
 188  * of the commits in the starting list. Injecting mass into a commit
 189  * is achieved by adding to its pending mass counter and, if it is not already
 190  * enqueued, enqueuing the commit in a list of pending commits, in latest
 191  * commit date first order.
 192  *
 193  * The algorithm then preceeds to visit each commit in the pending queue.
 194  * Upon each visit, the pending mass is added to the mass already seen for that
 195  * commit and then divided into N equal portions, where N is the number of
 196  * parents of the commit being visited. The divided portions are then injected
 197  * into each of the parents.
 198  *
 199  * The algorithm continues until we discover a commit which has seen all the
 200  * mass originally injected or until we run out of things to do.
 201  *
 202  * If we find a commit that has seen all the original mass, we have found
 203  * the common base of all the commits in the starting list.
 204  *
 205  * The algorithm does _not_ depend on accurate timestamps for correct operation.
 206  * However, reasonably sane (e.g. non-random) timestamps are required in order
 207  * to prevent an exponential performance characteristic. The occasional
 208  * timestamp inaccuracy will not dramatically affect performance but may
 209  * result in more nodes being processed than strictly necessary.
 210  *
 211  * This procedure sets *boundary to the address of the base commit. It returns
 212  * non-zero if, and only if, there was a problem parsing one of the
 213  * commits discovered during the traversal.
 214  */
 215 static int find_base_for_list(struct commit_list *list, struct commit **boundary)
 216 {
 217         int ret = 0;
 218         struct commit_list *cleaner = NULL;
 219         struct commit_list *pending = NULL;
 220         struct fraction injected;
 221         init_fraction(&injected);
 222         *boundary = NULL;
 223
 224         for (; list; list = list->next) {
 225                 struct commit *item = list->item;
 226
 227                 if (item->object.util) {
 228                         die("%s:%d:%s: logic error: this should not have happened - commit %s",
 229                             __FILE__, __LINE__, __FUNCTION__,
 230                             sha1_to_hex(item->object.sha1));
 231                 }
 232
 233                 new_mass_counter(list->item, get_one());
 234                 add(&injected, &injected, get_one());
 235
 236                 commit_list_insert(list->item, &cleaner);
 237                 commit_list_insert(list->item, &pending);
 238         }
 239
 240         while (!*boundary && pending && !ret) {
 241                 struct commit *latest = pop_commit(&pending);
 242                 struct mass_counter *latest_node = (struct mass_counter *) latest->object.util;
 243                 int num_parents;
 244
 245                 if ((ret = parse_commit(latest)))
 246                         continue;
 247                 add(&latest_node->seen, &latest_node->seen, &latest_node->pending);
 248
 249                 num_parents = count_parents(latest);
 250                 if (num_parents) {
 251                         struct fraction distribution;
 252                         struct commit_list *parents;
 253
 254                         divide(init_fraction(&distribution), &latest_node->pending, num_parents);
 255
 256                         for (parents = latest->parents; parents; parents = parents->next) {
 257                                 struct commit *parent = parents->item;
 258                                 struct mass_counter *parent_node = (struct mass_counter *) parent->object.util;
 259
 260                                 if (!parent_node) {
 261                                         parent_node = new_mass_counter(parent, &distribution);
 262                                         insert_by_date(&pending, parent);
 263                                         commit_list_insert(parent, &cleaner);
 264                                 } else {
 265                                         if (!compare(&parent_node->pending, get_zero()))
 266                                                 insert_by_date(&pending, parent);
 267                                         add(&parent_node->pending, &parent_node->pending, &distribution);
 268                                 }
 269                         }
 270
 271                         clear_fraction(&distribution);
 272                 }
 273
 274                 if (!compare(&latest_node->seen, &injected))
 275                         *boundary = latest;
 276                 copy(&latest_node->pending, get_zero());
 277         }
 278
 279         while (cleaner) {
 280                 struct commit *next = pop_commit(&cleaner);
 281                 free_mass_counter((struct mass_counter *) next->object.util);
 282                 next->object.util = NULL;
 283         }
 284
 285         if (pending)
 286                 free_commit_list(pending);
 287
 288         clear_fraction(&injected);
 289         return ret;
 290 }
 291
 292
 293 /*
 294  * Finds the base of an minimal, non-linear epoch, headed at head, by
 295  * applying the find_base_for_list to a list consisting of the parents
 296  */
 297 static int find_base(struct commit *head, struct commit **boundary)
 298 {
 299         int ret = 0;
 300         struct commit_list *pending = NULL;
 301         struct commit_list *next;
 302
 303         for (next = head->parents; next; next = next->next) {
 304                 commit_list_insert(next->item, &pending);
 305         }
 306         ret = find_base_for_list(pending, boundary);
 307         free_commit_list(pending);
 308
 309         return ret;
 310 }
 311
 312 /*
 313  * This procedure traverses to the boundary of the first epoch in the epoch
 314  * sequence of the epoch headed at head_of_epoch. This is either the end of
 315  * the maximal linear epoch or the base of a minimal non-linear epoch.
 316  *
 317  * The queue of pending nodes is sorted in reverse date order and each node
 318  * is currently in the queue at most once.
 319  */
 320 static int find_next_epoch_boundary(struct commit *head_of_epoch, struct commit **boundary)
 321 {
 322         int ret;
 323         struct commit *item = head_of_epoch;
 324
 325         ret = parse_commit(item);
 326         if (ret)
 327                 return ret;
 328
 329         if (HAS_EXACTLY_ONE_PARENT(item)) {
 330                 /*
 331                  * We are at the start of a maximimal linear epoch.
 332                  * Traverse to the end.
 333                  */
 334                 while (HAS_EXACTLY_ONE_PARENT(item) && !ret) {
 335                         item = item->parents->item;
 336                         ret = parse_commit(item);
 337                 }
 338                 *boundary = item;
 339
 340         } else {
 341                 /*
 342                  * Otherwise, we are at the start of a minimal, non-linear
 343                  * epoch - find the common base of all parents.
 344                  */
 345                 ret = find_base(item, boundary);
 346         }
 347
 348         return ret;
 349 }
 350
 351 /*
 352  * Returns non-zero if parent is known to be a parent of child.
 353  */
 354 static int is_parent_of(struct commit *parent, struct commit *child)
 355 {
 356         struct commit_list *parents;
 357         for (parents = child->parents; parents; parents = parents->next) {
 358                 if (!memcmp(parent->object.sha1, parents->item->object.sha1,
 359                             sizeof(parents->item->object.sha1)))
 360                         return 1;
 361         }
 362         return 0;
 363 }
 364
 365 /*
 366  * Pushes an item onto the merge order stack. If the top of the stack is
 367  * marked as being a possible "break", we check to see whether it actually
 368  * is a break.
 369  */
 370 static void push_onto_merge_order_stack(struct commit_list **stack, struct commit *item)
 371 {
 372         struct commit_list *top = *stack;
 373         if (top && (top->item->object.flags & DISCONTINUITY)) {
 374                 if (is_parent_of(top->item, item)) {
 375                         top->item->object.flags &= ~DISCONTINUITY;
 376                 }
 377         }
 378         commit_list_insert(item, stack);
 379 }
 380
 381 /*
 382  * Marks all interesting, visited commits reachable from this commit
 383  * as uninteresting. We stop recursing when we reach the epoch boundary,
 384  * an unvisited node or a node that has already been marking uninteresting.
 385  *
 386  * This doesn't actually mark all ancestors between the start node and the
 387  * epoch boundary uninteresting, but does ensure that they will eventually
 388  * be marked uninteresting when the main sort_first_epoch() traversal
 389  * eventually reaches them.
 390  */
 391 static void mark_ancestors_uninteresting(struct commit *commit)
 392 {
 393         unsigned int flags = commit->object.flags;
 394         int visited = flags & VISITED;
 395         int boundary = flags & BOUNDARY;
 396         int uninteresting = flags & UNINTERESTING;
 397         struct commit_list *next;
 398
 399         commit->object.flags |= UNINTERESTING;
 400
 401         /*
 402          * We only need to recurse if
 403          *      we are not on the boundary and
 404          *      we have not already been marked uninteresting and
 405          *      we have already been visited.
 406          *
 407          * The main sort_first_epoch traverse will mark unreachable
 408          * all uninteresting, unvisited parents as they are visited
 409          * so there is no need to duplicate that traversal here.
 410          *
 411          * Similarly, if we are already marked uninteresting
 412          * then either all ancestors have already been marked
 413          * uninteresting or will be once the sort_first_epoch
 414          * traverse reaches them.
 415          */
 416
 417         if (uninteresting || boundary || !visited)
 418                 return;
 419
 420         for (next = commit->parents; next; next = next->next)
 421                 mark_ancestors_uninteresting(next->item);
 422 }
 423
 424 /*
 425  * Sorts the nodes of the first epoch of the epoch sequence of the epoch headed at head
 426  * into merge order.
 427  */
 428 static void sort_first_epoch(struct commit *head, struct commit_list **stack)
 429 {
 430         struct commit_list *parents;
 431         struct commit_list *reversed_parents = NULL;
 432
 433         head->object.flags |= VISITED;
 434
 435         /*
 436          * parse_commit() builds the parent list in reverse order with respect
 437          * to the order of the git-commit-tree arguments. So we need to reverse
 438          * this list to output the oldest (or most "local") commits last.
 439          */
 440         for (parents = head->parents; parents; parents = parents->next)
 441                 commit_list_insert(parents->item, &reversed_parents);
 442
 443         /*
 444          * TODO: By sorting the parents in a different order, we can alter the
 445          * merge order to show contemporaneous changes in parallel branches
 446          * occurring after "local" changes. This is useful for a developer
 447          * when a developer wants to see all changes that were incorporated
 448          * into the same merge as her own changes occur after her own
 449          * changes.
 450          */
 451
 452         while (reversed_parents) {
 453                 struct commit *parent = pop_commit(&reversed_parents);
 454
 455                 if (head->object.flags & UNINTERESTING) {
 456                         /*
 457                          * Propagates the uninteresting bit to all parents.
 458                          * if we have already visited this parent, then
 459                          * the uninteresting bit will be propagated to each
 460                          * reachable commit that is still not marked
 461                          * uninteresting and won't otherwise be reached.
 462                          */
 463                         mark_ancestors_uninteresting(parent);
 464                 }
 465
 466                 if (!(parent->object.flags & VISITED)) {
 467                         if (parent->object.flags & BOUNDARY) {
 468                                 if (*stack) {
 469                                         die("something else is on the stack - %s",
 470                                             sha1_to_hex((*stack)->item->object.sha1));
 471                                 }
 472                                 push_onto_merge_order_stack(stack, parent);
 473                                 parent->object.flags |= VISITED;
 474
 475                         } else {
 476                                 sort_first_epoch(parent, stack);
 477                                 if (reversed_parents) {
 478                                         /*
 479                                          * This indicates a possible
 480                                          * discontinuity it may not be be
 481                                          * actual discontinuity if the head
 482                                          * of parent N happens to be the tail
 483                                          * of parent N+1.
 484                                          *
 485                                          * The next push onto the stack will
 486                                          * resolve the question.
 487                                          */
 488                                         (*stack)->item->object.flags |= DISCONTINUITY;
 489                                 }
 490                         }
 491                 }
 492         }
 493
 494         push_onto_merge_order_stack(stack, head);
 495 }
 496
 497 /*
 498  * Emit the contents of the stack.
 499  *
 500  * The stack is freed and replaced by NULL.
 501  *
 502  * Sets the return value to STOP if no further output should be generated.
 503  */
 504 static int emit_stack(struct commit_list **stack, emitter_func emitter)
 505 {
 506         unsigned int seen = 0;
 507         int action = CONTINUE;
 508
 509         while (*stack && (action != STOP)) {
 510                 struct commit *next = pop_commit(stack);
 511                 seen |= next->object.flags;
 512                 if (*stack)
 513                         action = (*emitter) (next);
 514         }
 515
 516         if (*stack) {
 517                 free_commit_list(*stack);
 518                 *stack = NULL;
 519         }
 520
 521         return (action == STOP || (seen & UNINTERESTING)) ? STOP : CONTINUE;
 522 }
 523
 524 /*
 525  * Sorts an arbitrary epoch into merge order by sorting each epoch
 526  * of its epoch sequence into order.
 527  *
 528  * Note: this algorithm currently leaves traces of its execution in the
 529  * object flags of nodes it discovers. This should probably be fixed.
 530  */
 531 static int sort_in_merge_order(struct commit *head_of_epoch, emitter_func emitter)
 532 {
 533         struct commit *next = head_of_epoch;
 534         int ret = 0;
 535         int action = CONTINUE;
 536
 537         ret = parse_commit(head_of_epoch);
 538
 539         next->object.flags |= BOUNDARY;
 540
 541         while (next && next->parents && !ret && (action != STOP)) {
 542                 struct commit *base = NULL;
 543
 544                 ret = find_next_epoch_boundary(next, &base);
 545                 if (ret)
 546                         return ret;
 547                 next->object.flags |= BOUNDARY;
 548                 if (base)
 549                         base->object.flags |= BOUNDARY;
 550
 551                 if (HAS_EXACTLY_ONE_PARENT(next)) {
 552                         while (HAS_EXACTLY_ONE_PARENT(next)
 553                                && (action != STOP)
 554                                && !ret) {
 555                                 if (next->object.flags & UNINTERESTING) {
 556                                         action = STOP;
 557                                 } else {
 558                                         action = (*emitter) (next);
 559                                 }
 560                                 if (action != STOP) {
 561                                         next = next->parents->item;
 562                                         ret = parse_commit(next);
 563                                 }
 564                         }
 565
 566                 } else {
 567                         struct commit_list *stack = NULL;
 568                         sort_first_epoch(next, &stack);
 569                         action = emit_stack(&stack, emitter);
 570                         next = base;
 571                 }
 572         }
 573
 574         if (next && (action != STOP) && !ret) {
 575                 (*emitter) (next);
 576         }
 577
 578         return ret;
 579 }
 580
 581 /*
 582  * Sorts the nodes reachable from a starting list in merge order, we
 583  * first find the base for the starting list and then sort all nodes
 584  * in this subgraph using the sort_first_epoch algorithm. Once we have
 585  * reached the base we can continue sorting using sort_in_merge_order.
 586  */
 587 int sort_list_in_merge_order(struct commit_list *list, emitter_func emitter)
 588 {
 589         struct commit_list *stack = NULL;
 590         struct commit *base;
 591         int ret = 0;
 592         int action = CONTINUE;
 593         struct commit_list *reversed = NULL;
 594
 595         for (; list; list = list->next) {
 596                 struct commit *next = list->item;
 597
 598                 if (!(next->object.flags & UNINTERESTING)) {
 599                         if (next->object.flags & DUPCHECK) {
 600                                 fprintf(stderr, "%s: duplicate commit %s ignored\n",
 601                                         __FUNCTION__, sha1_to_hex(next->object.sha1));
 602                         } else {
 603                                 next->object.flags |= DUPCHECK;
 604                                 commit_list_insert(list->item, &reversed);
 605                         }
 606                 }
 607         }
 608
 609         if (!reversed->next) {
 610                 /*
 611                  * If there is only one element in the list, we can sort it
 612                  * using sort_in_merge_order.
 613                  */
 614                 base = reversed->item;
 615         } else {
 616                 /*
 617                  * Otherwise, we search for the base of the list.
 618                  */
 619                 ret = find_base_for_list(reversed, &base);
 620                 if (ret)
 621                         return ret;
 622                 if (base)
 623                         base->object.flags |= BOUNDARY;
 624
 625                 while (reversed) {
 626                         sort_first_epoch(pop_commit(&reversed), &stack);
 627                         if (reversed) {
 628                                 /*
 629                                  * If we have more commits to push, then the
 630                                  * first push for the next parent may (or may
 631                                  * not) represent a discontinuity with respect
 632                                  * to the parent currently on the top of
 633                                  * the stack.
 634                                  *
 635                                  * Mark it for checking here, and check it
 636                                  * with the next push. See sort_first_epoch()
 637                                  * for more details.
 638                                  */
 639                                 stack->item->object.flags |= DISCONTINUITY;
 640                         }
 641                 }
 642
 643                 action = emit_stack(&stack, emitter);
 644         }
 645
 646         if (base && (action != STOP)) {
 647                 ret = sort_in_merge_order(base, emitter);
 648         }
 649
 650         return ret;
 651 }