BazaarInternals

Bazaar Internal Infrastructure

Status

Introduction

This specification discusses what internal infrastructure Bazaar needs to be flexibly upgraded and evolved as the BazaarNG Convergence occurs.

Rationale

The Bazaar codebase will be around for a while yet. There are facilities and libraries around that can save us from reimplementing the wheel as we add features and facilities. Additionally, having useful generic facilities can save a lot of time in handling minor issues within the program. If I know what infrastructure is most useful to the developers working on Baz, I can spend my baz development time producing it, enabling the other developers to be more efficient.

An initial list of concepts:

  • exception handling
  • pervasive talloc handling

Each infrastructure item should result in an RFC on the gnuarch.org wiki.

Scope and Use Cases

This document aims to enumerate and assess bazaar internal improvements to increase the effectiveness of community contributed time.

Use case: remove soft errors

For functions to both provide a simple interface where failures are fatal, and a robust interface where error handling is done by the caller baz current uses a 'soft errors' idiom where a flag is set. However this doesn't provide information to the caller, and requires extensive code changes to use safely. It has been a source of bugs in the past.

Suggested action: Provide a light weight exception-catching facility using talloc to free resources used during the call. BazaarExceptions. RobertCollins -- Implemented.

Use case: provide direct lookup from strings to objects

Bazaar has an efficient key-value lookup system in its assoc_table class, but this is not generally usable for other value types in the libarch code. Extending this would allow the archive management code, the inventory code, the bzr compatible tree logic, and potentially other code areas to become simpler by removing duplicate 'look-aside' tables that are working around this limitation. BazaarObjectMaps

Use case: make the bazaar code more transparent to new contributors

Bazaar currently uses a relatively limited set of types to represent the current state of a routine. I.e. it uses an  assoc_table  rather than a BazaarObjectMap. This style means that new programmers have to grok the link between the elements of a set of related variables rather than the interface for a clearly defined class. I.e. A map from String to BazaarFileId is more clear than an assoc_table from string to string, where the meaning of the value is essentially undefined until one reads the code.

Use case: clarify the usage of 0/1 parameters to functions

Many function calls in libarch accept long lists of 0 valued parameters, making it hard to tell what they are being used for - optional parameters, or Boolean flags or integers, or NULL pointers.

Use case: Make it easy to debug baz test failures

The baz test scripts set up isolated environments to avoid damaging the users environment. This makes debugging the cause of a test failure difficult. Its also unclear to someone not familiar with the environment how to proceed once an error occurs. Finally, the documentation on the test system is absent without leave.

Use case: reduce manual memory management

Baz is written in C, which provides no intrinsic memory management facilities. The hackerlab provided facilities are very low level with little assistance for the programmer. talloc has been very useful so far in baz, extending its use throughout the code base would reduce complex or duplicate dead-chicken code.

Use case: provide direct URL access

The URL support in bazaar revolves around the 'archive' concept. Current development such as SuperMirror archive lookups will require non 'archive' access to URL's.

Use case: provide easy class behaviors

The C vtable implementation in libarch is pretty standard C - which means no programmer support. As baz evolves towards BazaarNg more support will make it easier to maintain a high quality of code by preventing procedural idioms from dominating the code base. This should reduce explicit casting of virtual types, and provide setupmatic setup of the vtable for users of the code.

Implementation Plan

Use case: remove soft errors

Do a literature search for C exception libraries. If none can be found, introduce an exception handling framework using setjmp/longjmp and talloc to cleanup objects allocated by callees.

  • Implemented in robert.collins@canonical.com--general/talloc-except--2.0.1 on top of the cexcept C exception library.

=== Use case: provide direct lookup from strings to objects ===e

Generalize the current pointer_map lookup logic to be reusable by a macro framework. Currently it requires minor C code to be written to instantiate the type.

Use case: make the bazaar code more transparent to new contributors

Document where/when, why, and how to convert current sets-of-variables to typed objects with optional virtual methods.

Use case: clarify the usage of 0/1 parameters to functions

Provide a bool type compatible with the syntax of c99 bools. Encourage more use of NULL rather than 0 for pointers. Encourage the use of enums rather than magic value ints. This documentation should go on BazaarCodingStyle

Use case: Make it easy to debug baz test failures

Extend the test framework to optionally provide a subshell on failure. If not provided it would log how to get it provide this subshell. When the subshell is provided, it will provide diagnostics on the script, test, and other information, as well as any info that we can give on reproduction.

Additionally better documentation on invoking parts of the test suite will increase the devel-debug feedback cycle for programmers.

Use case: reduce manual memory managment

Extend the use of talloc to all self contained data structures in hackerlab and bazaar. Follow this up with judicious conversion of the most useful types - i.e. types that are encountered during exception unwinding to allow effective use of exceptions.

Use case: provide direct URL access

Review the pfs layer and identify what needs to be changed to provide direct URL access. This may be a bug or a layering problem requiring redesign. A further BOF is needed on this.

Use case: provide easy class behaviors

This should be deferred until classes are becoming a more common idiom. In the interim a literature search will be done to review C object frameworks so that we don't invent the wheel.

Data Preservation and Migration

Packages Affected

User Interface Requirements

Outstanding Issues

CategoryUdu CategorySpec

UbuntuDownUnder/BOFs/BazaarInternals (last edited 2008-08-06 16:22:55 by localhost)