From 4a15060bcbf38c550f7dcc86ceff277854f9eecf Mon Sep 17 00:00:00 2001 From: jbj Date: Thu, 19 Sep 2002 20:33:51 +0000 Subject: Initial revision CVS patchset: 5721 CVS date: 2002/09/19 20:33:51 --- db/docs/ref/distrib/port.html | 110 ++++++++++++++++++++++++++++++++ db/docs/ref/env/db_config.html | 51 +++++++++++++++ db/docs/ref/upgrade.4.1/cxx.html | 48 ++++++++++++++ db/docs/ref/upgrade.4.1/hash_nelem.html | 25 ++++++++ db/docs/ref/upgrade.4.1/java.html | 29 +++++++++ 5 files changed, 263 insertions(+) create mode 100644 db/docs/ref/distrib/port.html create mode 100644 db/docs/ref/env/db_config.html create mode 100644 db/docs/ref/upgrade.4.1/cxx.html create mode 100644 db/docs/ref/upgrade.4.1/hash_nelem.html create mode 100644 db/docs/ref/upgrade.4.1/java.html (limited to 'db/docs/ref') diff --git a/db/docs/ref/distrib/port.html b/db/docs/ref/distrib/port.html new file mode 100644 index 000000000..d453973e9 --- /dev/null +++ b/db/docs/ref/distrib/port.html @@ -0,0 +1,110 @@ + + + + + + +Berkeley DB Reference Guide: Porting Berkeley DB to new architectures + + + + + + +

Berkeley DB Reference Guide:
Distribution

PrevRefNext +
+

+

Porting Berkeley DB to new architectures

+

Berkeley DB is generally easy to port to new architectures. Berkeley DB was +designed to be as portable as possible, and has been ported to a wide +variety of systems, from Wind River's Tornado system, to VMS, to +Windows/NT and Windows/95, and most existing UNIX platforms. It runs +on 16, 32 and 64-bit machines, little or big-endian. The difficulty of +a port depends on how much of the ANSI C and POSIX 1003.1 standards the +new architecture offers. +

An abstraction layer separates the main Berkeley DB code from the operating +system and architecture specific components. This layer is comprised +of approximately 2500 lines of C language code, found in the os +subdirectory of the Berkeley DB distribution. The following list of files +include functionality that may need to be modified or implemented in +order to support a new architecture. Within each file, there is usually +one, but sometimes several functions (for example, the +os_alloc.c file contains the malloc, calloc, realloc, free, +and strdup functions). +

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source fileDescription
os_abs.cReturn if a filename is an absolute pathname
os_alloc.cANSI C malloc, calloc, realloc, strdup, free front-ends
os_clock.cReturn the current time-of-day
os_config.cReturn run-time configuration information
os_dir.cRead the filenames from a directory
os_errno.cSet/get the ANSI C errno value
os_fid.cCreate a unique ID for a file
os_fsync.cPOSIX 1003.1 fsync front-end
os_handle.cOpen file handles
os_id.cReturn thread ID
os_map.cMap a shared memory area
os_method.cRun-time replacement of system calls
os_oflags.cConvert POSIX 1003.1 open flags, modes to Berkeley DB flags
os_open.cOpen file handles
os_region.cMap a shared memory area
os_rename.cPOSIX 1003.1 rename call
os_root.cReturn if application has special permissions
os_rpath.cReturn last pathname separator
os_rw.cPOSIX 1003.1 read/write calls
os_seek.cPOSIX 1003.1 seek call
os_sleep.cCause a thread of control to release the CPU
os_spin.cReturn the times to spin while waiting for a mutex
os_stat.cPOSIX 1003.1 stat call
os_tmpdir.cSet the path for temporary files
os_unlink.cPOSIX 1003.1 unlink call
+

All but a few of these files contain relatively trivial pieces of code. +Typically, there is only a single version of the code for all platforms +Berkeley DB supports, and that code lives in the os directory of the +distribution. Where different code is required, the code is either +conditionally compiled or an entirely different version is written. For +example, VxWorks versions of some of these files can be found in the +distribution directory os_vxworks, and Win32 versions can be found in +os_win32. +

Historically, there are only two difficult questions to answer for each +new port. The first question is how to handle shared memory. In order +to write multiprocess database applications (not multithreaded, but +threads of control running in different address spaces), Berkeley DB must be +able to name pieces of shared memory and access them from multiple +processes. On UNIX/POSIX systems, we use mmap and +shmget for that purpose, but any interface that provides access +to named shared memory is sufficient. If you have a simple, flat +address space, you should be able to use the code in +os_vxworks/os_map.c as a starting point for the port. If you +are not intending to write multiprocess database applications, then +this won't be necessary, as Berkeley DB can simply allocate memory from the +heap if all threads of control will live in a single address space. +

The second question is mutex support. Berkeley DB requires some form of +self-blocking mutual exclusion mutex. Blocking mutexes are +preferred as they tend to be less CPU-expensive and less likely to cause +thrashing. If blocking mutexes are not available, however, test-and-set +will work as well. The code for mutexes is in two places in the system: +the include file dbinc/mutex.h, and the distribution directory +mutex. +

Berkeley DB uses the GNU autoconf tools for configuration on almost all of +the platforms it supports. Specifically, the include file +db_config.h configures the Berkeley DB build. The simplest way to +begin a port is to configure and build Berkeley DB on a UNIX or UNIX-like +system, and then take the Makefile and db_config.h +file created by that configuration, and modify it by hand to reflect +the needs of the new architecture. Unless you're already familiar with +the GNU autoconf toolset, we don't recommend you take the time to +integrate your changes back into the Berkeley DB autoconfiguration framework. +Instead, send Sleepycat Software context diffs of your changes and any +new source files you created, and we'll integrate the changes into our +source tree. +

Finally, we're happy to work with you on the port, or potentially, do +the port ourselves, if that is of interest to you. Regardless, if you +have any porting questions, just let us know, and we will be happy to +answer them. +

PrevRefNext +
+

Copyright Sleepycat Software + + diff --git a/db/docs/ref/env/db_config.html b/db/docs/ref/env/db_config.html new file mode 100644 index 000000000..bfb2afce2 --- /dev/null +++ b/db/docs/ref/env/db_config.html @@ -0,0 +1,51 @@ + + + + + + +Berkeley DB Reference Guide: DB_CONFIG configuration file + + + + + + + +

Berkeley DB Reference Guide:
Environment

PrevRefNext +
+

+

DB_CONFIG configuration file

+

Most of the configuration information that can be specified to +DB_ENV methods can also be specified using a configuration file. +If an environment home directory has been specified (either by the +application specifying a non-NULL db_home argument to +DB_ENV->open, or by the application setting the +DB_USE_ENVIRON or DB_USE_ENVIRON_ROOT flags and the +DB_HOME environment variable being set), any file named +DB_CONFIG in the database home directory will be read for lines +of the format NAME VALUE. +

One or more whitespace characters are used to delimit the two parts of +the line, and trailing whitespace characters are discarded. All empty +lines or lines whose first character is a whitespace or hash +(#) character will be ignored. Each line must specify both +the NAME and the VALUE of the pair. The specific NAME VALUE pairs are +documented in the manual for the corresponding methods (for example, +the DB_ENV->set_data_dir documentation includes NAME VALUE pair +information Berkeley DB administrators can use to configure locations for +database files). +

The DB_CONFIG configuration file is intended to allow database +environment administrators to customize environments independent of +applications using the environment. For example, a database +administrator can move the database log and data files to a different +location without application recompilation. In addition, because the +DB_CONFIG file is read when the database environment is opened, +it can be used to overrule application configuration done before that +time. For example a database administrator could override the +compiled-in application cache size to a size more appropriate for a +specific machine. +

PrevRefNext +
+

Copyright Sleepycat Software + + diff --git a/db/docs/ref/upgrade.4.1/cxx.html b/db/docs/ref/upgrade.4.1/cxx.html new file mode 100644 index 000000000..0e6958823 --- /dev/null +++ b/db/docs/ref/upgrade.4.1/cxx.html @@ -0,0 +1,48 @@ + + + + + + +Berkeley DB Reference Guide: Release 4.1: C++ exceptions + + + + + + +

Berkeley DB Reference Guide:
Upgrading Berkeley DB Applications

PrevRefNext +
+

+

Release 4.1: C++ exceptions

+

With default flags, the C++ DbEnv and Db classes +can throw exceptions from their constructors. For example, this can +happen if invalid parameters are passed in or the underlying C +structures could not be created. If the objects are created in an +environment that is not configured for exceptions (that is, the +DB_CXX_NO_EXCEPTIONS flag is specified), errors from the +constructor will be returned when the handle's open method is called. +

In addition, the behavior of the DbEnv and Db +destructors has changed to simplify exception handling in applications. +The destructors will now close the handle if the handle's close method +was not called prior to the object being destroyed. The return value +of the call is discarded, and no exceptions will be thrown. +Applications should call the close method in normal situations so any +errors while closing can be handled by the application. +

This change allows applications to be structured as follows: +

try {
+	DbEnv env(0);
+	env.open(/* ... */);
+	Db db(&env, 0);
+	db.open(/* ... */);
+	/* ... */
+	db.close(0);
+	env.close(0);
+} catch (DbException &dbe) {
+	// Handle the exception, the handles have already been closed.
+}
+

PrevRefNext +
+

Copyright Sleepycat Software + + diff --git a/db/docs/ref/upgrade.4.1/hash_nelem.html b/db/docs/ref/upgrade.4.1/hash_nelem.html new file mode 100644 index 000000000..1da26083d --- /dev/null +++ b/db/docs/ref/upgrade.4.1/hash_nelem.html @@ -0,0 +1,25 @@ + + + + + + +Berkeley DB Reference Guide: Release 4.1: DB->stat.hash_nelem + + + + + + +

Berkeley DB Reference Guide:
Upgrading Berkeley DB Applications

PrevRefNext +
+

+

Release 4.1: DB->stat.hash_nelem

+

The hash_nelem field of the DB->stat method for Hash +databases has been removed from the 4.1 release, this information is no +longer available to applications. +

PrevRefNext +
+

Copyright Sleepycat Software + + diff --git a/db/docs/ref/upgrade.4.1/java.html b/db/docs/ref/upgrade.4.1/java.html new file mode 100644 index 000000000..ac1f17654 --- /dev/null +++ b/db/docs/ref/upgrade.4.1/java.html @@ -0,0 +1,29 @@ + + + + + + +Berkeley DB Reference Guide: Release 4.1: Java exceptions + + + + + + +

Berkeley DB Reference Guide:
Upgrading Berkeley DB Applications

PrevRefNext +
+

+

Release 4.1: Java exceptions

+

The Java DbEnv constructor is now marked with "throws +DbException". This means applications must construct DbEnv +objects in a context where DbException throwables are +handled (either in a try/catch block or in a method that propagates the +exception up the stack). Note that previous versions of the Berkeley DB Java +API could throw this exception from the constructor but it was not +marked. +

PrevRefNext +
+

Copyright Sleepycat Software + + -- cgit v1.2.3