Added qtask_ordered, qtask_unordered and index_fasta examples.

The qtask programs demonstrate of use ordered and unordered result
processing from a thread pool.

The index_fasta and read_fast_index tools demonstrate the fasta
indexing capabilities.

Improved the Makefile and tidied up the indentation and code example
layout / structure in DEMO.md

Also several minor wording and spelling fixes.

Author: vasudeva8

samples/DEMO.md

@@ -2,7 +2,7 @@ HTS_DIR = ../
 include $(HTS_DIR)/htslib_static.mk
 
 CC = gcc
-CFLAGS = -Wall -g -O0
+CFLAGS = -Wall -O2
 
 #to statically link to libhts
 LDFLAGS = $(HTS_DIR)/libhts.a -L$(HTS_DIR) $(HTSLIB_static_LDFLAGS) $(HTSLIB_static_LIBS)
@@ -13,91 +13,104 @@ LDFLAGS = $(HTS_DIR)/libhts.a -L$(HTS_DIR) $(HTSLIB_static_LDFLAGS) $(HTSLIB_sta
 PRGS = flags split split2 cram read_fast read_header read_ref read_bam \
 	read_aux dump_aux add_header rem_header update_header mod_bam mod_aux \
 	mod_aux_ba write_fast idx_on_write read_reg read_multireg pileup \
-	mpileup modstate pileup_mod flags_field split_t1 split_t2
+	mpileup modstate pileup_mod flags_field split_t1 split_t2 \
+	read_fast_i qtask_ordered qtask_unordered index_fasta
 
 all: $(PRGS)
 
-flags:
+flags: flags_demo.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) flags_demo.c -o $@  $(LDFLAGS)
 
-split:
+split: split.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) split.c -o $@  $(LDFLAGS)
 
-split2:
+split2: split2.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) split2.c -o $@  $(LDFLAGS)
 
-cram:
+cram: cram.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) cram.c -o $@  $(LDFLAGS)
 
-read_fast:
+read_fast: read_fast.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) read_fast.c -o $@  $(LDFLAGS)
 
-read_header:
+read_header: read_header.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) read_header.c -o $@  $(LDFLAGS)
 
-read_ref:
+read_ref: read_refname.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) read_refname.c -o $@  $(LDFLAGS)
 
-read_bam:
+read_bam: read_bam.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) read_bam.c -o $@  $(LDFLAGS)
 
-read_aux:
+read_aux: read_aux.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) read_aux.c -o $@  $(LDFLAGS)
 
-dump_aux:
+dump_aux: dump_aux.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) dump_aux.c -o $@  $(LDFLAGS)
 
-add_header:
+add_header: add_header.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) add_header.c -o $@  $(LDFLAGS)
 
-rem_header:
+rem_header: rem_header.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) rem_header.c -o $@  $(LDFLAGS)
 
-update_header:
+update_header: update_header.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) update_header.c -o $@  $(LDFLAGS)
 
-mod_bam:
+mod_bam: mod_bam.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) mod_bam.c -o $@  $(LDFLAGS)
 
-mod_aux:
+mod_aux: mod_aux.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) mod_aux.c -o $@  $(LDFLAGS)
 
-mod_aux_ba:
+mod_aux_ba: mod_aux_ba.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) mod_aux_ba.c -o $@  $(LDFLAGS)
 
-write_fast:
+write_fast: write_fast.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) write_fast.c -o $@  $(LDFLAGS)
 
-idx_on_write:
+idx_on_write: index_write.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) index_write.c -o $@  $(LDFLAGS)
 
-read_reg:
+read_reg: index_reg_read.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) index_reg_read.c -o $@  $(LDFLAGS)
 
-read_multireg:
+read_multireg: index_multireg_read.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) index_multireg_read.c -o $@  $(LDFLAGS)
 
-pileup:
+read_fast_i: read_fast_index.c
+	$(CC) $(CFLAGS) -I $(HTS_DIR) read_fast_index.c -o $@  $(LDFLAGS)
+
+pileup: pileup.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) pileup.c -o $@  $(LDFLAGS)
 
-mpileup:
+mpileup: mpileup.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) mpileup.c -o $@  $(LDFLAGS)
 
-modstate:
+modstate: modstate.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) modstate.c -o $@  $(LDFLAGS)
 
-pileup_mod:
+pileup_mod: pileup_mod.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) pileup_mod.c -o $@  $(LDFLAGS)
 
-flags_field:
+flags_field: flags_htsopt_field.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) flags_htsopt_field.c -o $@  $(LDFLAGS)
 
-split_t1:
+split_t1: split_thread1.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) split_thread1.c -o $@  $(LDFLAGS)
 
-split_t2:
+split_t2: split_thread2.c
 	$(CC) $(CFLAGS) -I $(HTS_DIR) split_thread2.c -o $@  $(LDFLAGS)
 
+index_fasta: index_fasta.c
+	$(CC) $(CFLAGS) -I $(HTS_DIR) index_fasta.c -o $@  $(LDFLAGS)
+
+qtask_ordered: qtask_ordered.c
+	$(CC) $(CFLAGS) -I $(HTS_DIR) qtask_ordered.c -o $@  $(LDFLAGS)
+
+qtask_unordered: qtask_unordered.c
+	$(CC) $(CFLAGS) -I $(HTS_DIR) qtask_unordered.c -o $@  $(LDFLAGS)
+
 clean:
 	find . -name "*.o" | xargs rm -rf
 	find . -name "*.dSYM" | xargs rm -rf

samples/Makefile

@@ -4,7 +4,7 @@ data, and is the core library used by [samtools][2] and [bcftools][3].
 
 A set of sample programs are available which showcases the usage of APIs in HTSlib.
 They are based on version 1.17 of HTSLib and are mainly for demonstration of API usage.
-Further optimization and error handling might be required for actual usage.
+Further optimisation and error handling might be required for actual usage.
 
 
 [1]: http://samtools.github.io/hts-specs/
@@ -61,7 +61,7 @@ indexed.
 
 [Read_fast][Read_fast]
 
-  This application showcases the fasta/fastq data read.
+  This application showcases fasta/fastq data read without using index.
 
 [Read_header][Read_header]
 
@@ -72,7 +72,7 @@ indexed.
 [Read_ref][Read_ref]
 
   This application showcases the read and access of header data. It shows
-  all reference names which has length equal or greather to given input.
+  all reference names which has length equal or greater to given input.
 
 [Read_bam][Read_bam]
 
@@ -129,24 +129,33 @@ indexed.
 
 [Write_fast][Write_fast]
 
-  This application showcases the fasta/fastq data write. It appends a dummy
-  data to given file.
+  This application showcases the fasta/fastq data write. It appends data on
+  given file.
 
 [Index_write][Index_write]
 
   This application showcases the creation of index along with output
   creation. Based on file type and shift, it creates bai, csi or crai files.
 
+[Index_fast][Index_fast]
+
+  This application showcases index creation on fasta/fastq reference data.
+
 [Read_reg][Read_reg]:
 
   This application showcases the usage of region specification in alignment
   read.
 
 [Read_multireg][Read_multireg]:
 
-  This application showcases the usage of mulitple region specification in
+  This application showcases the usage of multiple region specification in
   alignment read.
 
+[Read_fast_index][Read_fast_index]
+
+  This application showcases the fasta/fastq data read using index. It takes a
+  region (reference name[:start-end]) and gets data from that region.
+
 [Pileup][Pileup]:
 
   This application showcases the pileup api, where all alignments covering a
@@ -181,8 +190,7 @@ indexed.
 
   This application showcases the use of threads in file handling. It saves
   the read1 and read2 as separate files in given directory, one as sam and
-  other as bam. 2 threads are used for read and 1 each dedicated for each
-  output file.
+  other as bam. 1 thread is used for read, 1 for sam write and 2 for bam write.
 
 [Split_thread2][Split_thread2]
 
@@ -191,6 +199,19 @@ indexed.
   and other as bam. A pool of 4 threads is created and shared for both read
   and write.
 
+[Qtask_ordered][Qtask_ordered]
+
+  This application showcases the use of queues and threads for custom
+  processing. Alignments in input file are updated with their GC ratio on a
+  custom aux tag. The processing may occur in any order but the results are
+  retrieved in same order as it was queued and saved to disk.
+
+[Qtask_unordered][Qtask_unordered]
+
+  This application showcases the use of queues and threads for custom
+  processing. The count of bases and GC ratio are calculated and displayed.
+  The order of counting is irrelevant and hence ordered retrieval is not used.
+
 ### More Information
 
 More detailed documentation is available in the [DEMO.md][DEMO] with worked
@@ -215,13 +236,17 @@ examples per demonstration tool.
 [Mod_aux_ba]: mod_aux_ba.c
 [Write_fast]: write_fast.c
 [Index_write]: index_write.c
+[Index_fasta]: index_fasta.c
 [Read_reg]: index_reg_read.c
 [Read_multireg]: index_multireg_read.c
+[Read_fast_index]: read_fast_index.c
 [Pileup]: pileup.c
 [Mpileup]: mpileup.c
 [Modstate]: modstate.c
 [Pileup_mod]: pileup_mod.c
 [Flags_field]: flags_htsopt_field.c
 [Split_thread1]: split_thread1.c
 [Split_thread2]: split_thread2.c
+[Qtask_ordered]: qtask_ordered.c
+[Qtask_unordered]: qtask_unordered.c
 [DEMO]: DEMO.md

samples/README.md

@@ -24,20 +24,20 @@ DEALINGS IN THE SOFTWARE
 
 */
 
-/* The pupose of this code is to demonstrate the library apis and need proper error handling and optimization */
+/* The purpose of this code is to demonstrate the library apis and need proper error handling and optimisation */
 
 #include <getopt.h>
 #include <unistd.h>
 #include <htslib/sam.h>
 
-/// print_usage - print the demo_usage
-/** @param fp pointer to the file / terminal to which demo_usage to be dumped
+/// print_usage - print the usage
+/** @param fp pointer to the file / terminal to which usage to be dumped
 returns nothing
 */
 static void print_usage(FILE *fp)
 {
     fprintf(fp, "Usage: add_header infile\n\
-Adds new header lines of SQ, RG, PG and CO typs\n");
+Adds new header lines of SQ, RG, PG and CO types\n");
     return;
 }
 

samples/add_header.c

@@ -24,14 +24,14 @@ DEALINGS IN THE SOFTWARE
 
 */
 
-/* The pupose of this code is to demonstrate the library apis and need proper error handling and optimization */
+/* The purpose of this code is to demonstrate the library apis and need proper error handling and optimisation */
 
 #include <getopt.h>
 #include <unistd.h>
 #include <htslib/sam.h>
 
-/// print_usage - print the demo_usage
-/** @param fp pointer to the file / terminal to which demo_usage to be dumped
+/// print_usage - print the usage
+/** @param fp pointer to the file / terminal to which usage to be dumped
 returns nothing
 */
 static void print_usage(FILE *fp)

samples/cram.c

@@ -24,14 +24,14 @@ DEALINGS IN THE SOFTWARE
 
 */
 
-/* The pupose of this code is to demonstrate the library apis and need proper error handling and optimization */
+/* The purpose of this code is to demonstrate the library apis and need proper error handling and optimisation */
 
 #include <getopt.h>
 #include <unistd.h>
 #include <htslib/sam.h>
 
-/// print_usage - print the demo_usage
-/** @param fp pointer to the file / terminal to which demo_usage to be dumped
+/// print_usage - print the usage
+/** @param fp pointer to the file / terminal to which usage to be dumped
 returns nothing
 */
 static void print_usage(FILE *fp)
@@ -92,7 +92,7 @@ int printauxdata(FILE *fp, char type, int32_t idx, const uint8_t *data)
         fprintf(fp, "%c", auxBType);
         for (i = 0; i < auxBcnt; ++i) {                                                     //iterate the array
             fprintf(fp, ",");
-            //calling recurssively  with index to reuse a few lines
+            //calling recursively  with index to reuse a few lines
             if (printauxdata(fp, auxBType, i, data) == EXIT_FAILURE) {
                 return EXIT_FAILURE;
             }

samples/dump_aux.c

@@ -24,14 +24,14 @@ DEALINGS IN THE SOFTWARE
 
 */
 
-/* The pupose of this code is to demonstrate the library apis and need proper error handling and optimization */
+/* The purpose of this code is to demonstrate the library apis and need proper error handling and optimisation */
 
 #include <getopt.h>
 #include <unistd.h>
 #include <htslib/sam.h>
 
-/// print_usage - show flags_demo usage
-/** @param fp pointer to the file / terminal to which demo_usage to be dumped
+/// print_usage - show usage
+/** @param fp pointer to the file / terminal to which usage to be dumped
 returns nothing
 */
 static void print_usage(FILE *fp)

samples/flags_demo.c

@@ -24,14 +24,14 @@ DEALINGS IN THE SOFTWARE
 
 */
 
-/* The pupose of this code is to demonstrate the library apis and need proper error handling and optimization */
+/* The purpose of this code is to demonstrate the library apis and need proper error handling and optimisation */
 
 #include <getopt.h>
 #include <unistd.h>
 #include <htslib/sam.h>
 
-/// print_usage - show flags_demo usage
-/** @param fp pointer to the file / terminal to which demo_usage to be dumped
+/// print_usage - show usage
+/** @param fp pointer to the file / terminal to which usage to be dumped
 returns nothing
 */
 static void print_usage(FILE *fp)