Rename pg_restore -m to -j, and add documentation about what good numbers

are.  per discussion on hackers

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 4971836bab8ecad27481fd77fa2d1b52d8d8e4fe..053bcba87da29daea960ba15ccfa6d2bcdd3aed5 100644 (file)
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  
@@ -215,6 +215,46 @@
       
      
 
+     
+      -j number-of-jobs
+      --jobs=number-of-jobs
+      
+       
+        Run the most time-consuming parts
+        of pg_restore — those which load data,
+        create indexes, or create constraints — using multiple
+        concurrent jobs.  This option can dramatically reduce the time
+        to restore a large database to a server running on a
+        multi-processor machine.
+       
+
+       
+        Each job is one process or one thread, depending on the
+        operating system, and uses a separate connection to the
+        server.
+       
+
+       
+        The optimal value for this option depends on the hardware
+        setup of the server, of the client, and of the network.
+        Factors include the number of CPU cores and the disk setup.  A
+        good place to start is the number of CPU cores on the server,
+        but values larger than that can also lead to faster restore
+        times in many cases.  Of course, values that are too high will
+        lead to decreasing performance because of thrashing.
+       
+
+       
+        Only the custom archive format is supported with this option.
+        The input file must be a regular file (not, for example, a
+        pipe).  This option is ignored when emitting a script rather
+        than connecting directly to a database server.  Also, multiple
+        jobs cannot be used together with the
+        option --single-transaction.
+       
+      
+     
+
      
       -l
       --list
@@ -241,28 +281,6 @@
       
      
 
-     
-      -m number-of-threads
-      --multi-thread=number-of-threads
-      
-       
-        Run the most time-consuming parts of pg_restore
-        — those which load data, create indexes, or create
-        constraints — using multiple concurrent connections to the
-        database. This option can dramatically reduce the time to restore a
-        large database to a server running on a multi-processor machine.
-       
-
-       
-        This option is ignored when emitting a script rather than connecting
-        directly to a database server.  Multiple threads cannot be used
-        together with --single-transaction.  Also, the input
-        must be a plain file (not, for example, a pipe), and at present only
-        the custom archive format is supported.
-       
-      
-     
-
      
       -n namespace
       --schema=schema

diff --git a/src/bin/pg_dump/pg_backup.h b/src/bin/pg_dump/pg_backup.h
index 3e50b6b39a821c8bcf1e1b53c39b6daf5a11180a..839a9fec601f643986ad00096f1a9ca20ead67c3 100644 (file)
--- a/src/bin/pg_dump/pg_backup.h
+++ b/src/bin/pg_dump/pg_backup.h
@@ -15,7 +15,7 @@
  *
  *
  * IDENTIFICATION
- *     $PostgreSQL: pgsql/src/bin/pg_dump/pg_backup.h,v 1.50 2009/02/26 16:02:37 petere Exp $
+ *     $PostgreSQL: pgsql/src/bin/pg_dump/pg_backup.h,v 1.51 2009/03/20 09:21:08 petere Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -139,7 +139,7 @@ typedef struct _restoreOptions
    int         suppressDumpWarnings;   /* Suppress output of WARNING entries
                                         * to stderr */
    bool        single_txn;
-   int         number_of_threads;
+   int         number_of_jobs;
 
    bool       *idWanted;       /* array showing which dump IDs to emit */
 } RestoreOptions;

diff --git a/src/bin/pg_dump/pg_backup_archiver.c b/src/bin/pg_dump/pg_backup_archiver.c
index 148aca4ef6c445b87049bddf5b5f77104942c906..f0ff3e7aa062294a2762d472693caa6fcd4edc26 100644 (file)
--- a/src/bin/pg_dump/pg_backup_archiver.c
+++ b/src/bin/pg_dump/pg_backup_archiver.c
@@ -15,7 +15,7 @@
  *
  *
  * IDENTIFICATION
- *     $PostgreSQL: pgsql/src/bin/pg_dump/pg_backup_archiver.c,v 1.167 2009/03/13 22:50:44 tgl Exp $
+ *     $PostgreSQL: pgsql/src/bin/pg_dump/pg_backup_archiver.c,v 1.168 2009/03/20 09:21:08 petere Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -354,7 +354,7 @@ RestoreArchive(Archive *AHX, RestoreOptions *ropt)
     *
     * In parallel mode, turn control over to the parallel-restore logic.
     */
-   if (ropt->number_of_threads > 1 && ropt->useDB)
+   if (ropt->number_of_jobs > 1 && ropt->useDB)
        restore_toc_entries_parallel(AH);
    else
    {
@@ -3061,7 +3061,7 @@ static void
 restore_toc_entries_parallel(ArchiveHandle *AH)
 {
    RestoreOptions *ropt = AH->ropt;
-   int         n_slots = ropt->number_of_threads;
+   int         n_slots = ropt->number_of_jobs;
    ParallelSlot *slots;
    int         work_status;
    int         next_slot;

diff --git a/src/bin/pg_dump/pg_restore.c b/src/bin/pg_dump/pg_restore.c
index c557f9706fe9d25190d5680884067c883587b6f7..69c805ce463a0ab83f6c0182852fb2d00d71b84c 100644 (file)
--- a/src/bin/pg_dump/pg_restore.c
+++ b/src/bin/pg_dump/pg_restore.c
@@ -34,7 +34,7 @@
  *
  *
  * IDENTIFICATION
- *     $PostgreSQL: pgsql/src/bin/pg_dump/pg_restore.c,v 1.95 2009/03/11 03:33:29 adunstan Exp $
+ *     $PostgreSQL: pgsql/src/bin/pg_dump/pg_restore.c,v 1.96 2009/03/20 09:21:09 petere Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -93,8 +93,8 @@ main(int argc, char **argv)
        {"host", 1, NULL, 'h'},
        {"ignore-version", 0, NULL, 'i'},
        {"index", 1, NULL, 'I'},
+       {"jobs", 1, NULL, 'j'},
        {"list", 0, NULL, 'l'},
-       {"multi-thread", 1, NULL, 'm'},
        {"no-privileges", 0, NULL, 'x'},
        {"no-acl", 0, NULL, 'x'},
        {"no-owner", 0, NULL, 'O'},
@@ -146,7 +146,7 @@ main(int argc, char **argv)
        }
    }
 
-   while ((c = getopt_long(argc, argv, "acCd:ef:F:h:iI:lL:m:n:Op:P:RsS:t:T:U:vwWxX:1",
+   while ((c = getopt_long(argc, argv, "acCd:ef:F:h:iI:j:lL:n:Op:P:RsS:t:T:U:vwWxX:1",
                            cmdopts, NULL)) != -1)
    {
        switch (c)
@@ -181,6 +181,10 @@ main(int argc, char **argv)
                /* ignored, deprecated option */
                break;
 
+           case 'j':           /* number of restore jobs */
+               opts->number_of_jobs = atoi(optarg);
+               break;
+
            case 'l':           /* Dump the TOC summary */
                opts->tocSummary = 1;
                break;
@@ -189,10 +193,6 @@ main(int argc, char **argv)
                opts->tocFile = strdup(optarg);
                break;
 
-           case 'm':           /* number of restore threads */
-               opts->number_of_threads = atoi(optarg);
-               break;
-
            case 'n':           /* Dump data for this schema only */
                opts->schemaNames = strdup(optarg);
                break;
@@ -318,9 +318,9 @@ main(int argc, char **argv)
    }
 
    /* Can't do single-txn mode with multiple connections */
-   if (opts->single_txn && opts->number_of_threads > 1)
+   if (opts->single_txn && opts->number_of_jobs > 1)
    {
-       fprintf(stderr, _("%s: cannot specify both --single-transaction and multiple threads\n"),
+       fprintf(stderr, _("%s: cannot specify both --single-transaction and multiple jobs\n"),
                progname);
        exit(1);
    }
@@ -417,9 +417,9 @@ usage(const char *progname)
    printf(_("  -C, --create             create the target database\n"));
    printf(_("  -e, --exit-on-error      exit on error, default is to continue\n"));
    printf(_("  -I, --index=NAME         restore named index\n"));
+   printf(_("  -j, --jobs=NUM           use this many parallel jobs to restore\n"));
    printf(_("  -L, --use-list=FILENAME  use table of contents from this file for\n"
         "                           selecting/ordering output\n"));
-   printf(_("  -m, --multi-thread=NUM   use this many parallel connections to restore\n"));
    printf(_("  -n, --schema=NAME        restore only objects in this schema\n"));
    printf(_("  -O, --no-owner           skip restoration of object ownership\n"));
    printf(_("  -P, --function=NAME(args)\n"