From 3c48c960903dfbe900755f0ab4f3b679b2bd32d0 Mon Sep 17 00:00:00 2001
From: Hasindu Gamaarachchi <hasindu2008@gmail.com>
Date: Mon, 28 Aug 2023 11:02:10 +1000
Subject: [PATCH 01/11] no timestamp check for index_load_with

---
 .../low_level_api/slow5_idx_load_with.md      |  8 +++---
 src/slow5_idx.c                               | 26 ++++++++++++-------
 2 files changed, 19 insertions(+), 15 deletions(-)

diff --git a/docs/slow5_api/low_level_api/slow5_idx_load_with.md b/docs/slow5_api/low_level_api/slow5_idx_load_with.md
index 34d853e..f852f5a 100755
--- a/docs/slow5_api/low_level_api/slow5_idx_load_with.md
+++ b/docs/slow5_api/low_level_api/slow5_idx_load_with.md
@@ -1,15 +1,13 @@
 # slow5_idx_load_with
 
 ## NAME
-slow5_idx_load_with - loads the index file for a SLOW5 file given a file path for the index
+slow5_idx_load_with - loads the index file for a SLOW5 file for a user specified file path for the index
 
 ## SYNOPSYS
-`int slow5_idx_load_with(slow5_with_file_t *s5p, const char *pathname)`
+`int slow5_idx_load_with(slow5_file_t *s5p, const char *pathname)`
 
 ## DESCRIPTION
-`slow5_idx_load_with()` loads an index file for a SLOW5 file pointed by *s5p* into the memory from the disk and associates the index with *s5p*. If the index file is not found, the index is first created and written to the disk.
-
-`slow5_idx_load_with()` could be called instead of `slow5_idx_load_with()` when the index file is at a custom location.
+`slow5_idx_load_with()` loads an index file located at *pathname* for a SLOW5 file pointed by *s5p* into the memory from the disk and associates the index with *s5p*. If the index file is not found, it will error out.
 
 ## RETURN VALUE
 Upon successful completion, `slow5_idx_load_with()` returns a non-negative integer. Otherwise, a negative value is returned.
diff --git a/src/slow5_idx.c b/src/slow5_idx.c
index 36f5979..f300ed9 100644
--- a/src/slow5_idx.c
+++ b/src/slow5_idx.c
@@ -31,17 +31,23 @@ static inline struct slow5_idx *slow5_idx_init_empty(void) {
     return index;
 }
 
-static inline int slow5_idx_load_fp(struct slow5_idx *index, struct slow5_file *s5p, FILE *index_fp) {
+static inline int slow5_idx_load_fp(struct slow5_idx *index, struct slow5_file *s5p, FILE *index_fp, int8_t check_ts) {
 
     index->fp = index_fp;
-    int err;
-    if (slow5_filestamps_cmp(index->pathname, s5p->meta.pathname, &err) < 0.0) {
-        SLOW5_WARNING("Index file '%s' is older than slow5 file '%s'.",
-                index->pathname, s5p->meta.pathname);
-    }
-    if (err == -1) {
-        return -1;
+
+    if(check_ts){
+        int err;
+        if (slow5_filestamps_cmp(index->pathname, s5p->meta.pathname, &err) < 0.0) {
+            SLOW5_WARNING("Index file '%s' is older than slow5 file '%s'.",
+                    index->pathname, s5p->meta.pathname);
+        }
+        if (err == -1) {
+            return -1;
+        }
+    } else {
+        SLOW5_INFO("Custom index file '%s' is being used. Time stamps not checked.", index->pathname);
     }
+
     if (slow5_idx_read(index) != 0) {
         return -1;
     }
@@ -79,7 +85,7 @@ struct slow5_idx *slow5_idx_init_with(struct slow5_file *s5p, const char *pathna
         slow5_idx_free(index);
         return NULL;
     } else {
-        if (slow5_idx_load_fp(index, s5p, index_fp) != 0) {
+        if (slow5_idx_load_fp(index, s5p, index_fp, 0) != 0) {
             slow5_idx_free(index);
             return NULL;
         }
@@ -127,7 +133,7 @@ struct slow5_idx *slow5_idx_init(struct slow5_file *s5p) {
         fclose(index->fp);
         index->fp = NULL;
     } else {
-        if (slow5_idx_load_fp(index, s5p, index_fp) != 0) {
+        if (slow5_idx_load_fp(index, s5p, index_fp, 1) != 0) {
             slow5_idx_free(index);
             return NULL;
         }

From a8a5afe5b938c6cfbf997b018804f0250356c7d1 Mon Sep 17 00:00:00 2001
From: Hasindu Gamaarachchi <hasindu2008@gmail.com>
Date: Wed, 20 Sep 2023 16:14:34 +1000
Subject: [PATCH 02/11] add slow5_batch_encode

---
 include/slow5/slow5_mt.h | 1 +
 src/slow5_mt.c           | 9 +++++++++
 2 files changed, 10 insertions(+)

diff --git a/include/slow5/slow5_mt.h b/include/slow5/slow5_mt.h
index a444662..2a75ee4 100644
--- a/include/slow5/slow5_mt.h
+++ b/include/slow5/slow5_mt.h
@@ -51,6 +51,7 @@ slow5_batch_t* slow5_init_batch(int batch_capacity);
 int slow5_get_next_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int batch_size);
 int slow5_get_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, char **rid, int num_rid);
 int slow5_write_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int batch_size);
+int slow5_encode_batch(slow5_mt_t *core, slow5_batch_t *db, int batch_size);
 void slow5_free_batch(slow5_batch_t *read_batch);
 void slow5_free_mt(slow5_mt_t *mt);
 
diff --git a/src/slow5_mt.c b/src/slow5_mt.c
index f7b9849..cfa3341 100644
--- a/src/slow5_mt.c
+++ b/src/slow5_mt.c
@@ -361,6 +361,11 @@ int slow5_get_next_batch(slow5_mt_t *core, slow5_batch_t *db, int batch_size){
     return num_read;
 }
 
+int slow5_encode_batch(slow5_mt_t *core, slow5_batch_t *db, int batch_size){
+    db->n_rec = batch_size;
+    slow5_work_db(core,db,slow5_work_per_single_read3);
+    return db->n_rec;
+}
 
 int slow5_write_batch(slow5_mt_t *core, slow5_batch_t *db, int batch_size){
 
@@ -501,6 +506,10 @@ int slow5_get_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, char **rid, int n
     fprintf(stderr,"slow5lib has not been compiled with lazy multithreading support\n");
     exit(EXIT_FAILURE);
 }
+int slow5_encode_batch(slow5_mt_t *core, slow5_batch_t *db, int batch_size){
+    fprintf(stderr,"slow5lib has not been compiled with lazy multithreading support\n");
+    exit(EXIT_FAILURE);
+}
 int slow5_write_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int batch_size){
     fprintf(stderr,"slow5lib has not been compiled with lazy multithreading support\n");
     exit(EXIT_FAILURE);

From df3aaf4c149556d5820a1ccf199956e4d9417f0c Mon Sep 17 00:00:00 2001
From: Hasindu Gamaarachchi <hasindu2008@gmail.com>
Date: Sat, 23 Sep 2023 11:25:58 +1000
Subject: [PATCH 03/11] expose two internal functions

---
 src/slow5_idx.c | 8 ++++----
 src/slow5_idx.h | 2 ++
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/src/slow5_idx.c b/src/slow5_idx.c
index f300ed9..d9aa270 100644
--- a/src/slow5_idx.c
+++ b/src/slow5_idx.c
@@ -14,11 +14,11 @@ extern enum slow5_exit_condition_opt  slow5_exit_condition;
 #define BUF_INIT_CAP (20*1024*1024)
 #define SLOW5_INDEX_BUF_INIT_CAP (64) // 2^6 TODO is this too little?
 
-static inline struct slow5_idx *slow5_idx_init_empty(void);
+
 static int slow5_idx_build(struct slow5_idx *index, struct slow5_file *s5p);
-static int slow5_idx_read(struct slow5_idx *index);
+int slow5_idx_read(struct slow5_idx *index);
 
-static inline struct slow5_idx *slow5_idx_init_empty(void) {
+struct slow5_idx *slow5_idx_init_empty(void) {
 
     struct slow5_idx *index = (struct slow5_idx *) calloc(1, sizeof *index);
     if(!index){
@@ -404,7 +404,7 @@ int slow5_idx_write(struct slow5_idx *index, struct slow5_version version) {
     return 0;
 }
 
-static int slow5_idx_read(struct slow5_idx *index) {
+int slow5_idx_read(struct slow5_idx *index) {
 
     struct slow5_version max_supported = SLOW5_VERSION_ARRAY;
     const char magic[] = SLOW5_INDEX_MAGIC_NUMBER;
diff --git a/src/slow5_idx.h b/src/slow5_idx.h
index 740729e..05a328e 100644
--- a/src/slow5_idx.h
+++ b/src/slow5_idx.h
@@ -47,6 +47,8 @@ struct slow5_idx {
 
 struct slow5_idx *slow5_idx_init(struct slow5_file *s5p);
 struct slow5_idx *slow5_idx_init_with(struct slow5_file *s5p, const char *pathname);
+struct slow5_idx *slow5_idx_init_empty(void);
+int slow5_idx_read(struct slow5_idx *index);
 
 /**
  * Create the index file for slow5 file.

From d6e36bccd8c1d009c246ec075dd6d87da4332fe2 Mon Sep 17 00:00:00 2001
From: Hasindu Gamaarachchi <hasindu2008@gmail.com>
Date: Sat, 23 Sep 2023 11:26:26 +1000
Subject: [PATCH 04/11] update docs

---
 docs/slow5_api/slow5_internal.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/slow5_api/slow5_internal.md b/docs/slow5_api/slow5_internal.md
index ed70444..3090837 100755
--- a/docs/slow5_api/slow5_internal.md
+++ b/docs/slow5_api/slow5_internal.md
@@ -40,6 +40,9 @@ DO NOT USE.
 * slow5_hdr_set
 * slow5_hdr_add_rg_data
 
+* slow5_idx_init_empty (used in slow5curl)
+* slow5_idx_read (used in slow5curl)
+
 <!--
 int slow5_hdr_fwrite(FILE *fp, struct slow5_hdr *header, enum slow5_fmt format, slow5_press_method_t comp)
 int slow5_rec_fwrite(FILE *fp, struct slow5_rec *read, struct slow5_aux_meta *aux_meta, enum slow5_fmt format, struct slow5_press *compress)

From dbc4e3e0eab570cc5d58031ee5382bc4d97d9339 Mon Sep 17 00:00:00 2001
From: Hasindu Gamaarachchi <hasindu2008@gmail.com>
Date: Thu, 16 Nov 2023 20:31:42 +1100
Subject: [PATCH 05/11] fix workflow and add more

---
 .github/workflows/c-cpp.yml  | 11 +++++++++++
 .github/workflows/python.yml |  4 ++--
 docs/slow5_api/slow5.md      |  3 +++
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/c-cpp.yml b/.github/workflows/c-cpp.yml
index 534259a..f8870da 100644
--- a/.github/workflows/c-cpp.yml
+++ b/.github/workflows/c-cpp.yml
@@ -107,6 +107,17 @@ jobs:
       run: make clean && make CC=icc -j8 zstd=1
     - name: test zstd
       run: make test zstd=1 CC=icc
+  ubuntu_22:
+    name: Ubuntu 22
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v2
+    - name: install packages
+      run: sudo apt-get update && sudo apt-get install zlib1g-dev
+    - name: build-gcc
+      run: make -j8
+    - name: test-gcc
+      run: make test
   os_x_11:
     name: OSX 11
     runs-on: macos-11
diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml
index 3196a69..01bde46 100644
--- a/.github/workflows/python.yml
+++ b/.github/workflows/python.yml
@@ -82,7 +82,7 @@ jobs:
     steps:
     - uses: actions/checkout@v2
     - name: install packages
-      run: pip3 install numpy
+      run: pip3 install numpy setuptools
     - name: build
       run: make pyslow5
     - name: test
@@ -93,7 +93,7 @@ jobs:
     steps:
     - uses: actions/checkout@v2
     - name: install packages
-      run: pip3 install numpy
+      run: pip3 install numpy setuptools
     - name: build
       run: make pyslow5
     - name: test
diff --git a/docs/slow5_api/slow5.md b/docs/slow5_api/slow5.md
index d4ef72e..2d90112 100755
--- a/docs/slow5_api/slow5.md
+++ b/docs/slow5_api/slow5.md
@@ -141,6 +141,9 @@ High-level API consists of following functions:
 
 Low-level API allows much more efficient access to BLOW5 files compared to the high-level API.  Low-level API is documented [here](slow5_low_level_api.md).
 
+### Extra multi-threaded API
+
+An optional built-in multithreaded API is under construction. See the [examples](https://github.com/hasindu2008/slow5lib/tree/master/examples/mt) for now. If you intend to use it, request through an [issue](https://github.com/hasindu2008/slow5lib/issues), so that we can finalise and document it.
 
 ## CITATION
 

From 24bac4d9ca54b43475798b78791c631566fca7a7 Mon Sep 17 00:00:00 2001
From: Hasindu Gamaarachchi <hasindu2008@gmail.com>
Date: Thu, 16 Nov 2023 20:40:41 +1100
Subject: [PATCH 06/11] setup.py update

---
 setup.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/setup.py b/setup.py
index 775efd9..fd0ea49 100644
--- a/setup.py
+++ b/setup.py
@@ -89,7 +89,7 @@ def readme():
 
 setup(
     name = 'pyslow5',
-    version='1.1.0-dirty',
+    version='1.1.0-dev',
     url = 'https://github.com/hasindu2008/slow5lib',
     description='slow5lib python bindings',
     long_description=readme(),

From 277973371baa9ba3430c13e351cebaf9dcd7005b Mon Sep 17 00:00:00 2001
From: Hasindu Gamaarachchi <hasindu2008@gmail.com>
Date: Thu, 16 Nov 2023 20:44:43 +1100
Subject: [PATCH 07/11] add note

---
 include/slow5/slow5_mt.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/slow5/slow5_mt.h b/include/slow5/slow5_mt.h
index 7f30e35..e8b2c9e 100644
--- a/include/slow5/slow5_mt.h
+++ b/include/slow5/slow5_mt.h
@@ -55,7 +55,7 @@ slow5_batch_t* slow5_init_batch(int batch_capacity);
 int slow5_get_next_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int batch_size);
 int slow5_get_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, char **rid, int num_rid);
 int slow5_write_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int batch_size);
-int slow5_encode_batch(slow5_mt_t *core, slow5_batch_t *db, int batch_size);
+int slow5_encode_batch(slow5_mt_t *core, slow5_batch_t *db, int batch_size); //used by slow5curl
 void slow5_free_batch(slow5_batch_t *read_batch);
 void slow5_free_mt(slow5_mt_t *mt);
 

From 7f40e57fadfa761b9503eebfc6040404f902e57f Mon Sep 17 00:00:00 2001
From: Hasindu Gamaarachchi <hasindu2008@gmail.com>
Date: Fri, 17 Nov 2023 14:58:09 +1100
Subject: [PATCH 08/11] easy multi-thread API

---
 docs/slow5_api/mt_api/slow5_free_batch.md     | 29 ++++++++++
 docs/slow5_api/mt_api/slow5_free_mt.md        | 27 +++++++++
 docs/slow5_api/mt_api/slow5_get_batch.md      | 27 +++++++++
 docs/slow5_api/mt_api/slow5_get_next_batch.md | 27 +++++++++
 docs/slow5_api/mt_api/slow5_init_batch.md     | 29 ++++++++++
 docs/slow5_api/mt_api/slow5_init_mt.md        | 31 +++++++++++
 docs/slow5_api/mt_api/slow5_write_batch.md    | 28 ++++++++++
 docs/slow5_api/slow5.md                       |  6 +-
 docs/slow5_api/slow5_low_level_api.md         |  2 +
 docs/slow5_api/slow5_mt_api.md                | 55 +++++++++++++++++++
 examples/mt/README.md                         |  6 +-
 include/slow5/slow5_mt.h                      |  2 +-
 12 files changed, 262 insertions(+), 7 deletions(-)
 create mode 100755 docs/slow5_api/mt_api/slow5_free_batch.md
 create mode 100755 docs/slow5_api/mt_api/slow5_free_mt.md
 create mode 100755 docs/slow5_api/mt_api/slow5_get_batch.md
 create mode 100755 docs/slow5_api/mt_api/slow5_get_next_batch.md
 create mode 100755 docs/slow5_api/mt_api/slow5_init_batch.md
 create mode 100755 docs/slow5_api/mt_api/slow5_init_mt.md
 create mode 100755 docs/slow5_api/mt_api/slow5_write_batch.md
 create mode 100755 docs/slow5_api/slow5_mt_api.md

diff --git a/docs/slow5_api/mt_api/slow5_free_batch.md b/docs/slow5_api/mt_api/slow5_free_batch.md
new file mode 100755
index 0000000..7ea6b12
--- /dev/null
+++ b/docs/slow5_api/mt_api/slow5_free_batch.md
@@ -0,0 +1,29 @@
+# slow5_free_batch
+
+## NAME
+
+slow5_free_batch - frees up a slow5 record batch
+
+## SYNOPSYS
+
+`void slow5_free_batch(slow5_batch_t *read_batch)`
+
+## DESCRIPTION
+
+`slow5_free_batch()` 
+
+
+## RETURN VALUE
+
+
+## ERRORS
+
+
+## NOTES
+
+
+## EXAMPLES
+
+
+## SEE ALSO
+
diff --git a/docs/slow5_api/mt_api/slow5_free_mt.md b/docs/slow5_api/mt_api/slow5_free_mt.md
new file mode 100755
index 0000000..7683e73
--- /dev/null
+++ b/docs/slow5_api/mt_api/slow5_free_mt.md
@@ -0,0 +1,27 @@
+# slow5_free_mt
+
+## NAME
+
+slow5_free_mt - frees up a slow5 multi-thread structure
+
+## SYNOPSYS
+
+`void slow5_free_mt(slow5_mt_t *mt)`
+
+## DESCRIPTION
+
+
+## RETURN VALUE
+
+
+## ERRORS
+
+
+## NOTES
+
+
+## EXAMPLES
+
+
+## SEE ALSO
+
diff --git a/docs/slow5_api/mt_api/slow5_get_batch.md b/docs/slow5_api/mt_api/slow5_get_batch.md
new file mode 100755
index 0000000..58fec45
--- /dev/null
+++ b/docs/slow5_api/mt_api/slow5_get_batch.md
@@ -0,0 +1,27 @@
+# slow5_get_batch
+
+## NAME
+
+slow5_get_batch - fetches a batch of SLOW5 records corresponding to a given batch of read ID
+
+## SYNOPSYS
+
+`int slow5_get_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, char **rid, int num_rid)`
+
+## DESCRIPTION
+
+
+## RETURN VALUE
+
+
+## ERRORS
+
+
+## NOTES
+
+
+## EXAMPLES
+
+
+## SEE ALSO
+
diff --git a/docs/slow5_api/mt_api/slow5_get_next_batch.md b/docs/slow5_api/mt_api/slow5_get_next_batch.md
new file mode 100755
index 0000000..0580ca7
--- /dev/null
+++ b/docs/slow5_api/mt_api/slow5_get_next_batch.md
@@ -0,0 +1,27 @@
+# slow5_get_next_batch
+
+## NAME
+
+slow5_get_next_batch - fetches the next batch of records at the current file pointer of a SLOW5 file
+
+## SYNOPSYS
+
+`int slow5_get_next_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int batch_size)`
+
+## DESCRIPTION
+
+
+## RETURN VALUE
+
+
+## ERRORS
+
+
+## NOTES
+
+
+## EXAMPLES
+
+
+## SEE ALSO
+
diff --git a/docs/slow5_api/mt_api/slow5_init_batch.md b/docs/slow5_api/mt_api/slow5_init_batch.md
new file mode 100755
index 0000000..ed33f02
--- /dev/null
+++ b/docs/slow5_api/mt_api/slow5_init_batch.md
@@ -0,0 +1,29 @@
+# slow5_init_batch
+
+## NAME
+
+slow5_init_batch - initialises a slow5 record batch
+
+## SYNOPSYS
+
+`slow5_batch_t* slow5_init_batch(int batch_capacity)`
+
+## DESCRIPTION
+
+`slow5_init_batch()` 
+
+
+## RETURN VALUE
+
+
+## ERRORS
+
+
+## NOTES
+
+
+## EXAMPLES
+
+
+## SEE ALSO
+
diff --git a/docs/slow5_api/mt_api/slow5_init_mt.md b/docs/slow5_api/mt_api/slow5_init_mt.md
new file mode 100755
index 0000000..3f068d1
--- /dev/null
+++ b/docs/slow5_api/mt_api/slow5_init_mt.md
@@ -0,0 +1,31 @@
+# slow5_init_mt
+
+## NAME
+
+slow5_init_mt - initialises a slow5 multi-thread structure
+
+## SYNOPSYS
+
+`slow5_mt_t *slow5_init_mt(int num_thread, slow5_file_t *s5p)`
+
+## DESCRIPTION
+
+`slow5_init_mt()` initialises a slow5 multi-thread structure for the number of threads specified by *num_thread* for and a SLOW5 file pointed by *s5p*.
+
+The argument *s5p* points to a *slow5_file_t* opened using `slow5_open()`.
+
+
+## RETURN VALUE
+
+
+## ERRORS
+
+
+## NOTES
+
+
+## EXAMPLES
+
+
+## SEE ALSO
+
diff --git a/docs/slow5_api/mt_api/slow5_write_batch.md b/docs/slow5_api/mt_api/slow5_write_batch.md
new file mode 100755
index 0000000..8c769bb
--- /dev/null
+++ b/docs/slow5_api/mt_api/slow5_write_batch.md
@@ -0,0 +1,28 @@
+# slow5_write_batch
+
+## NAME
+
+slow5_write_batch - writes a batch of SLOW5 records to a SLOW5 file
+
+## SYNOPSYS
+
+`int slow5_write_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int batch_size)`
+
+## DESCRIPTION
+
+
+
+## RETURN VALUE
+
+
+## ERRORS
+
+
+## NOTES
+
+
+## EXAMPLES
+
+
+## SEE ALSO
+
diff --git a/docs/slow5_api/slow5.md b/docs/slow5_api/slow5.md
index 2d90112..9e183e4 100755
--- a/docs/slow5_api/slow5.md
+++ b/docs/slow5_api/slow5.md
@@ -135,15 +135,15 @@ High-level API consists of following functions:
 * [slow5_set_press](slow5_set_press.md)<br/>
   &nbsp;&nbsp;&nbsp;&nbsp;sets the compression method for a BLOW5 file opened for writing
 
-
+You may also refer to examples [here](https://github.com/hasindu2008/slow5lib/tree/master/examples).
 
 ### Low-level API for reading and writing SLOW5 files
 
 Low-level API allows much more efficient access to BLOW5 files compared to the high-level API.  Low-level API is documented [here](slow5_low_level_api.md).
 
-### Extra multi-threaded API
+### Easy multi-thread API
 
-An optional built-in multithreaded API is under construction. See the [examples](https://github.com/hasindu2008/slow5lib/tree/master/examples/mt) for now. If you intend to use it, request through an [issue](https://github.com/hasindu2008/slow5lib/issues), so that we can finalise and document it.
+The easy multi-thread (called *mt* API) API allows the user to access SLOW5 using multiple threads, simply by specifying the number of threads, rather than needing to write their own multi-threading code. mt API is documented [here](slow5_mt_api.md). Note that this API is for your convenience, rather than for efficiency.
 
 ## CITATION
 
diff --git a/docs/slow5_api/slow5_low_level_api.md b/docs/slow5_api/slow5_low_level_api.md
index 9019454..4f58f95 100755
--- a/docs/slow5_api/slow5_low_level_api.md
+++ b/docs/slow5_api/slow5_low_level_api.md
@@ -42,4 +42,6 @@ Low-level API allows much more efficient access to BLOW5 files compared to the h
   &nbsp;&nbsp;&nbsp;&nbsp;writes an encoded SLOW5 record to a SLOW5 file
 
 
+You may also refer to examples [here](https://github.com/hasindu2008/slow5lib/tree/master/examples/adv).
+
 **If you want any other functionality than what is described above, please open a GitHub issue so such functionality exposed, rather than trying to use internal functions by browsing the code. Such undocumented functions are subject to change.**
diff --git a/docs/slow5_api/slow5_mt_api.md b/docs/slow5_api/slow5_mt_api.md
new file mode 100755
index 0000000..2cd34f3
--- /dev/null
+++ b/docs/slow5_api/slow5_mt_api.md
@@ -0,0 +1,55 @@
+# slow5lib Easy multi-thread API
+
+**NOTE: This API is in beta stage and the documentation is sparse. If something is not clear do not hesitate to open an [issue](https://github.com/hasindu2008/slow5lib/issues).**
+
+The easy multi-thread (called *mt* API) API allows the user to access SLOW5 using multiple threads, simply by specifying the number of threads, rather than needing to write their own multi-threading code. Note that this API is for your convenience, rather than for efficiency. It is not meant to be used by a programmer who has the expertise to write multi-threaded code and use the slow5 low-level API directly. While fetching using this API would be faster than using a single thread, it would not be as efficient as using low-level API functions directly from the programmer's own multi-threaded code.
+
+To use this API, include <slow5/slow5_mt.h> in your programme. Make sure to explicitly enable easy multi-thread API as `make slow5_mt=1`, during compile time of slow5lib.
+
+## Data structures
+
+The *slow5_mt_t* structure stores internal multi-threading related data. This structure has the following form:
+
+```
+typedef struct {
+    // private members that are not to be directly accessed*/
+} slow5_mt_t;
+```
+
+The *slow5_batch_t* structure stores a batch of SLOW5 records. This structure has the following form:
+
+```
+typedef struct {
+    // private members that are not to be directly accessed*/
+    slow5_rec_t **slow5_rec;
+} slow5_batch_t;
+```
+
+## API functions
+
+### Common
+
+* [slow5_init_mt](mt_api/slow5_init_mt.md)<br/>
+  &nbsp;&nbsp;&nbsp;&nbsp;initialises a slow5 multi-thread structure
+* [slow5_free_mt](mt_api/slow5_free_mt.md)<br/>
+  &nbsp;&nbsp;&nbsp;&nbsp;frees up a slow5 multi-thread structure
+* [slow5_init_batch](mt_api/slow5_init_batch.md)<br/>
+  &nbsp;&nbsp;&nbsp;&nbsp;initialises a slow5 record batch
+* [slow5_free_batch](mt_api/slow5_free_batch.md)<br/>
+  &nbsp;&nbsp;&nbsp;&nbsp;frees up a slow5 record batch
+
+### Reading and access
+
+* [slow5_get_next_batch](mt_api/slow5_get_next_batch.md)<br/>
+  &nbsp;&nbsp;&nbsp;&nbsp;fetches the next batch of records at the current file pointer of a SLOW5 file
+* [slow5_get_batch](mt_api/slow5_get_batch.md)<br/>
+  &nbsp;&nbsp;&nbsp;&nbsp;fetches a batch of SLOW5 records corresponding to a given batch of read ID
+
+
+### Writing and editing
+
+* [slow5_write_batch](mt_api/slow5_write_batch.md)<br/>
+  &nbsp;&nbsp;&nbsp;&nbsp;writes a batch of SLOW5 records to a SLOW5 file
+
+
+You may also refer to the examples [here](https://github.com/hasindu2008/slow5lib/tree/master/examples/mt) on how these functions can be used.
diff --git a/examples/mt/README.md b/examples/mt/README.md
index 504b5e2..a08d764 100755
--- a/examples/mt/README.md
+++ b/examples/mt/README.md
@@ -1,12 +1,12 @@
 # slow5lib mt Examples
 
-**WARNING: This API is under development. There could be bugs**
+**WARNING: This API is in beta stage.**
 
 **This is not meant to be used by a programmer who has the expertise to write efficient multi-threaded code and use the slow5 low-level API directly. Such advanced examples are at [advanced examples](../adv/)**
 
-This directory contains examples that uses the built in multi-threaded API in slow5lib.  For these examples to work you must build slow5lib with multi-threaded API as `make slow5_mt=1`. To link against slow5lib built with multi-threaded API, make sure to append `-lpthread` flag.
+This directory contains examples that uses the easy multi-thread API in slow5lib.  For these examples to work you must build slow5lib with easy multi-thread API enabled as `make slow5_mt=1`. To link against slow5lib built with easy multi-thread API, make sure to append `-lpthread` flag.
 
-- *mt.c* demonstrates how to use multi-threaded API to first write and then fetch a batch of slow5/blow5 records in parallel.
+- *mt.c* demonstrates how to use the easy multi-thread API to first write and then fetch a batch of slow5/blow5 records in parallel.
 - *lazymt.c* demonstrates how to use the lazy function to do the same as above, which is meant for a lazy programmer.
 
 You can invoke [build.sh](build.sh) from slow5lib directory as `examples/mt/build.sh` to compile the example programmes. Have a look at the script to see the commands used for compiling and linking. Also make sure you get familiar with the basic examples first, before trying these.
diff --git a/include/slow5/slow5_mt.h b/include/slow5/slow5_mt.h
index e8b2c9e..c8e84cd 100644
--- a/include/slow5/slow5_mt.h
+++ b/include/slow5/slow5_mt.h
@@ -9,7 +9,7 @@ extern "C" {
 #endif /* __cplusplus */
 
 /**************************************************************************************************
- ***  Multi-threading API *************************************************************************
+ ***  Easy Multi-thread API *************************************************************************
  **************************************************************************************************/
 
 /**************** This API is still in beta stage, there could be bugs *************************/

From 02f7e7bc0df502afe7475a3f49bd1d76e21c5bc1 Mon Sep 17 00:00:00 2001
From: Hasindu Gamaarachchi <hasindu2008@gmail.com>
Date: Sat, 18 Nov 2023 00:26:43 +1100
Subject: [PATCH 09/11] update docs

---
 docs/slow5_api/mt_api/slow5_free_batch.md     |  45 ++++++-
 docs/slow5_api/mt_api/slow5_free_mt.md        |  36 +++++-
 docs/slow5_api/mt_api/slow5_get_batch.md      |  75 ++++++++++++
 docs/slow5_api/mt_api/slow5_get_next_batch.md |  64 +++++++++-
 docs/slow5_api/mt_api/slow5_init_batch.md     |  46 +++++++-
 docs/slow5_api/mt_api/slow5_init_mt.md        |  44 ++++++-
 docs/slow5_api/mt_api/slow5_write_batch.md    | 110 +++++++++++++++++-
 docs/slow5_api/slow5_mt_api.md                |   6 +-
 examples/mt/mt.c                              |  34 +++++-
 include/slow5/slow5_mt.h                      |  14 +--
 src/slow5_mt.c                                |  73 +++++-------
 11 files changed, 461 insertions(+), 86 deletions(-)

diff --git a/docs/slow5_api/mt_api/slow5_free_batch.md b/docs/slow5_api/mt_api/slow5_free_batch.md
index 7ea6b12..aa7a967 100755
--- a/docs/slow5_api/mt_api/slow5_free_batch.md
+++ b/docs/slow5_api/mt_api/slow5_free_batch.md
@@ -10,20 +10,55 @@ slow5_free_batch - frees up a slow5 record batch
 
 ## DESCRIPTION
 
-`slow5_free_batch()` 
-
+The `slow5_free_batch()` function frees the memory of a *slow5_batch_t* structure pointed by *read_batch*, which must have been returned by a previous call to `slow5_init_batch()`.
 
 ## RETURN VALUE
 
+None
+
+## EXAMPLES
 
-## ERRORS
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+#include <slow5/slow5_mt.h>
 
+#define FILE_PATH "examples/example.slow5"
 
-## NOTES
+int main(){
 
+ slow5_file_t *sp = slow5_open(FILE_PATH,"r");
+    if(sp==NULL){
+        fprintf(stderr,"Error in opening file\n");
+        exit(EXIT_FAILURE);
+    }
 
-## EXAMPLES
+    int batch_size = 4096;
+    int num_thread = 8;
+
+    slow5_mt_t *mt = slow5_init_mt(num_thread,sp);
+    if (mt==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising multi-thread struct\n");
+        exit(EXIT_FAILURE);
+    }
+
+    slow5_batch_t *read_batch = slow5_init_batch(batch_size);
+    if (read_batch==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising slow5 record batch\n");
+        exit(EXIT_FAILURE);
+    }
+
+    // ...
+
+    slow5_free_batch(read_batch);
+    slow5_free_mt(mt);
+    slow5_close(sp);
 
+    return 0;
+}
+```
 
 ## SEE ALSO
 
+[slow5_init_batch()](slow5_init_batch.md)
\ No newline at end of file
diff --git a/docs/slow5_api/mt_api/slow5_free_mt.md b/docs/slow5_api/mt_api/slow5_free_mt.md
index 7683e73..3d68eab 100755
--- a/docs/slow5_api/mt_api/slow5_free_mt.md
+++ b/docs/slow5_api/mt_api/slow5_free_mt.md
@@ -10,18 +10,48 @@ slow5_free_mt - frees up a slow5 multi-thread structure
 
 ## DESCRIPTION
 
+The `slow5_free_mt()` function frees the memory of a slow5_mt_t structure pointed by mt, which must have been returned by a previous call to `slow5_init_mt()`.
 
 ## RETURN VALUE
 
+None
 
-## ERRORS
+## EXAMPLES
 
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+#include <slow5/slow5_mt.h>
 
-## NOTES
+#define FILE_PATH "examples/example.slow5"
 
+int main(){
 
-## EXAMPLES
+    slow5_file_t *sp = slow5_open(FILE_PATH,"r");
+    if(sp==NULL){
+        fprintf(stderr,"Error in opening file\n");
+        exit(EXIT_FAILURE);
+    }
+
+    int num_thread = 8;
+
+    slow5_mt_t *mt = slow5_init_mt(num_thread,sp);
+    if (mt==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising multi-thread struct\n");
+        exit(EXIT_FAILURE);
+    }
+
+    //...
+
+    slow5_free_mt(mt);
+    slow5_close(sp);
+
+    return 0;
+}
+```
 
 
 ## SEE ALSO
 
+[slow5_init_mt()](slow5_init_mt.md)
\ No newline at end of file
diff --git a/docs/slow5_api/mt_api/slow5_get_batch.md b/docs/slow5_api/mt_api/slow5_get_batch.md
index 58fec45..d7fce3f 100755
--- a/docs/slow5_api/mt_api/slow5_get_batch.md
+++ b/docs/slow5_api/mt_api/slow5_get_batch.md
@@ -10,18 +10,93 @@ slow5_get_batch - fetches a batch of SLOW5 records corresponding to a given batc
 
 ## DESCRIPTION
 
+`slow5_get_batch()` fetches a batch of record from a SLOW5 file associated with *mt* for a specified list of read IDs. The list of read must be pointed by *rid* and the the size of the list must be specified by *num_rid*.
 
 ## RETURN VALUE
 
+The number of records fetched.
+
+## NOTES
+
+*num_rid* must be less than or equal to the capacity of the read_batch.
 
 ## ERRORS
 
+Currently, in case of error, this function will exit the programme. Proper error handling might be introduced in future, where a negative number return is indicative of error.
 
 ## NOTES
 
 
 ## EXAMPLES
 
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+#include <slow5/slow5_mt.h>
+
+#define FILE_PATH "examples/example.slow5"
+
+int main(){
+
+    slow5_file_t *sp = slow5_open(FILE_PATH,"r");
+    if(sp==NULL){
+       fprintf(stderr,"Error in opening file\n");
+       exit(EXIT_FAILURE);
+    }
+
+    slow5_rec_t **rec = NULL;
+    int ret=0;
+
+    ret = slow5_idx_load(sp);
+    if(ret<0){
+        fprintf(stderr,"Error in loading index\n");
+        exit(EXIT_FAILURE);
+    }
+
+    int num_rid = 4;
+    int num_thread = 2;
+    int batch_size = 4096;
+    char *rid[num_rid];
+    rid[0]="r4";
+    rid[1]="r1",
+    rid[2]="r2";
+    rid[3]="r5";
+
+    slow5_mt_t *mt = slow5_init_mt(num_thread,sp);
+    if (mt==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising multi-thread struct\n");
+        exit(EXIT_FAILURE);
+    }
+
+    slow5_batch_t *read_batch = slow5_init_batch(batch_size);
+    if (read_batch==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising slow5 record batch\n");
+        exit(EXIT_FAILURE);
+    }
+
+    ret = slow5_get_batch(mt, read_batch, rid, num_rid);
+    if(ret!=num_rid){
+        fprintf(stderr,"Error in fetching all records\n");
+        exit(EXIT_FAILURE);
+    }
+
+    for(int i=0;i<ret;i++){
+        rec = read_batch->slow5_rec;
+        uint64_t len_raw_signal = rec[i]->len_raw_signal;
+        printf("%s\t%ld\n",rec[i]->read_id,len_raw_signal);
+    }
+
+    slow5_free_batch(read_batch);
+    slow5_free_mt(mt);
+
+    slow5_idx_unload(sp);
+    slow5_close(sp);
+
+    return 0;
+}
+```
 
 ## SEE ALSO
 
+[slow5_get()](slow5_get_next_batch.md)
\ No newline at end of file
diff --git a/docs/slow5_api/mt_api/slow5_get_next_batch.md b/docs/slow5_api/mt_api/slow5_get_next_batch.md
index 0580ca7..a5d10c2 100755
--- a/docs/slow5_api/mt_api/slow5_get_next_batch.md
+++ b/docs/slow5_api/mt_api/slow5_get_next_batch.md
@@ -6,22 +6,80 @@ slow5_get_next_batch - fetches the next batch of records at the current file poi
 
 ## SYNOPSYS
 
-`int slow5_get_next_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int batch_size)`
+`int slow5_get_next_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int num_reads)`
 
 ## DESCRIPTION
 
+`slow5_get_next_batch()` fetches the next *num_reads* number of records from a SLOW5 file associated with *mt* at the current file pointer into a *slow5_batch_t*.
 
 ## RETURN VALUE
 
+The number of records fetched.
 
-## ERRORS
+## NOTES
 
+*num_reads* must be less than or equal to the capacity of the read_batch.
 
-## NOTES
+## ERRORS
 
+Currently, in case of error, this function will exit the programme. Proper error handling might be introduced in future, where a negative number return is indicative of error.
 
 ## EXAMPLES
 
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+#include <slow5/slow5_mt.h>
+
+#define FILE_PATH "examples/example.slow5"
+
+int main(){
+
+    slow5_file_t *sp = slow5_open(FILE_PATH,"r");
+    if(sp==NULL){
+        fprintf(stderr,"Error in opening file\n");
+        exit(EXIT_FAILURE);
+    }
+
+    slow5_rec_t **rec = NULL;
+    int ret=0;
+    int batch_size = 4096;
+    int num_thread = 8;
+
+    slow5_mt_t *mt = slow5_init_mt(num_thread,sp);
+    if (mt==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising multi-thread struct\n");
+        exit(EXIT_FAILURE);
+    }
+
+    slow5_batch_t *read_batch = slow5_init_batch(batch_size);
+    if (read_batch==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising slow5 record batch\n");
+        exit(EXIT_FAILURE);
+    }
+
+    while((ret = slow5_get_next_batch(mt,read_batch,4096)) > 0){
+
+        for(int i=0;i<ret;i++){
+            rec = read_batch->slow5_rec;
+            uint64_t len_raw_signal = rec[i]->len_raw_signal;
+            printf("%s\t%ld\n",rec[i]->read_id,len_raw_signal);
+        }
+
+        if(ret<4096){ //this indicates nothing left to read //better handling of errors may be introduced in future
+            break;
+        }
+    }
+
+    slow5_free_batch(read_batch);
+    slow5_free_mt(mt);
+    slow5_close(sp);
+
+    return 0;
+}
+```
 
 ## SEE ALSO
 
+[slow5_get()](slow5_get_batch.md)
\ No newline at end of file
diff --git a/docs/slow5_api/mt_api/slow5_init_batch.md b/docs/slow5_api/mt_api/slow5_init_batch.md
index ed33f02..5302167 100755
--- a/docs/slow5_api/mt_api/slow5_init_batch.md
+++ b/docs/slow5_api/mt_api/slow5_init_batch.md
@@ -10,20 +10,60 @@ slow5_init_batch - initialises a slow5 record batch
 
 ## DESCRIPTION
 
-`slow5_init_batch()` 
+`slow5_init_batch()` function initialises and returns a batch of empty SLOW5 records. The number of empty records in the batch will be what is specified by *batch_capacity*. The returned SLOW5 record batch must be later freed by calling `slow5_free_batch()`.
 
 
 ## RETURN VALUE
 
+Upon successful completion, `slow5_init_batch()` returns a *slow5_batch_t* pointer.
 
 ## ERRORS
 
+Currently, in case of error, this function will exit the programme. Proper error handling might be introduced in future, where a NULL return is indicative of error.
 
-## NOTES
+## EXAMPLES
 
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+#include <slow5/slow5_mt.h>
 
-## EXAMPLES
+#define FILE_PATH "examples/example.slow5"
+
+int main(){
+
+ slow5_file_t *sp = slow5_open(FILE_PATH,"r");
+    if(sp==NULL){
+        fprintf(stderr,"Error in opening file\n");
+        exit(EXIT_FAILURE);
+    }
+
+    int batch_size = 4096;
+    int num_thread = 8;
+
+    slow5_mt_t *mt = slow5_init_mt(num_thread,sp);
+    if (mt==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising multi-thread struct\n");
+        exit(EXIT_FAILURE);
+    }
+
+    slow5_batch_t *read_batch = slow5_init_batch(batch_size);
+    if (read_batch==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising slow5 record batch\n");
+        exit(EXIT_FAILURE);
+    }
+
+    // ...
+
+    slow5_free_batch(read_batch);
+    slow5_free_mt(mt);
+    slow5_close(sp);
 
+    return 0;
+}
+```
 
 ## SEE ALSO
 
+[slow5_free_batch()](slow5_free_batch.md)
diff --git a/docs/slow5_api/mt_api/slow5_init_mt.md b/docs/slow5_api/mt_api/slow5_init_mt.md
index 3f068d1..1fb7191 100755
--- a/docs/slow5_api/mt_api/slow5_init_mt.md
+++ b/docs/slow5_api/mt_api/slow5_init_mt.md
@@ -10,22 +10,56 @@ slow5_init_mt - initialises a slow5 multi-thread structure
 
 ## DESCRIPTION
 
-`slow5_init_mt()` initialises a slow5 multi-thread structure for the number of threads specified by *num_thread* for and a SLOW5 file pointed by *s5p*.
-
-The argument *s5p* points to a *slow5_file_t* opened using `slow5_open()`.
+`slow5_init_mt()` initialises and returns a slow5 multi-thread structure for the number of threads specified by *num_thread*. The argument *s5p* must to a *slow5_file_t* opened using `slow5_open()`. The returned slow5 multi-thread structure must be later freed by calling `slow5_free_mt()`.
 
 
 ## RETURN VALUE
 
+Upon successful completion, `slow5_init_mt()` returns a slow5_mt_t pointer.
 
-## ERRORS
 
+## ERRORS
 
-## NOTES
+Currently, in case of error, this function will exit the programme. Proper error handling might be introduced in future, where a NULL return is indicative of error.
 
 
 ## EXAMPLES
 
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+#include <slow5/slow5_mt.h>
+
+#define FILE_PATH "examples/example.slow5"
+
+int main(){
+
+    slow5_file_t *sp = slow5_open(FILE_PATH,"r");
+    if(sp==NULL){
+        fprintf(stderr,"Error in opening file\n");
+        exit(EXIT_FAILURE);
+    }
+
+    int num_thread = 8;
+
+    slow5_mt_t *mt = slow5_init_mt(num_thread,sp);
+    if (mt==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising multi-thread struct\n");
+        exit(EXIT_FAILURE);
+    }
+
+    //...
+
+    slow5_free_mt(mt);
+    slow5_close(sp);
+
+    return 0;
+}
+```
+
 
 ## SEE ALSO
 
+[slow5_free_mt()](slow5_free_mt.md)
+
diff --git a/docs/slow5_api/mt_api/slow5_write_batch.md b/docs/slow5_api/mt_api/slow5_write_batch.md
index 8c769bb..dddae2c 100755
--- a/docs/slow5_api/mt_api/slow5_write_batch.md
+++ b/docs/slow5_api/mt_api/slow5_write_batch.md
@@ -6,23 +6,123 @@ slow5_write_batch - writes a batch of SLOW5 records to a SLOW5 file
 
 ## SYNOPSYS
 
-`int slow5_write_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int batch_size)`
+`int slow5_write_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int num_reads)`
 
 ## DESCRIPTION
 
+`slow5_write_batch()` writes a batch of SLOW5 records pointed by *read_batch* to a SLOW5 file associated with *mt*.
 
 
 ## RETURN VALUE
 
+The number of records written.
 
 ## ERRORS
 
-
-## NOTES
-
+Currently, in case of error, this function will exit the programme. Proper error handling might be introduced in future, where a negative number return is indicative of error.
 
 ## EXAMPLES
 
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+#include <slow5/slow5_mt.h>
+
+#define FILE_PATH "test.blow5"
+
+int main(){
+
+    slow5_file_t *sf = slow5_open(FILE_PATH,"w");
+    if(sf==NULL){
+        fprintf(stderr,"Error in opening file\n");
+        exit(EXIT_FAILURE);
+    }
+
+    slow5_hdr_t *header=sf->header;
+
+    //add a header group attribute called run_id
+    if (slow5_hdr_add_attr("run_id", header) != 0){
+        fprintf(stderr,"Error adding run_id attribute\n");
+        exit(EXIT_FAILURE);
+    }
+
+    //set the run_id attribute to "run_0" for read group 0
+    if (slow5_hdr_set("run_id", "run_0", 0, header) != 0){
+        fprintf(stderr,"Error setting run_id attribute in read group 0\n");
+        exit(EXIT_FAILURE);
+    }
+
+    if(slow5_hdr_write(sf) < 0){
+        fprintf(stderr,"Error writing header!\n");
+        exit(EXIT_FAILURE);
+    }
+
+    int ret=0;
+    int batch_size = 16;
+    int num_thread = 8;
+
+    slow5_mt_t *mt = slow5_init_mt(num_thread,sf);
+    if (mt==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising multi-thread struct\n");
+        exit(EXIT_FAILURE);
+    }
+
+    slow5_batch_t *read_batch = slow5_init_batch(batch_size);
+    if (read_batch==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising slow5 record batch\n");
+        exit(EXIT_FAILURE);
+    }
+
+    slow5_rec_t **rec = read_batch->slow5_rec;
+
+    for(int i=0;i<batch_size;i++){
+
+        slow5_rec_t *slow5_record = rec[i] = slow5_rec_init();
+
+        if(slow5_record == NULL){
+            fprintf(stderr,"Could not allocate space for a slow5 record.");
+            exit(EXIT_FAILURE);
+        }
+
+        char tmp_read_id[100];
+        sprintf(tmp_read_id,"read_id_%d",i);
+        slow5_record -> read_id = strdup(tmp_read_id);
+        if(slow5_record->read_id == NULL){
+            fprintf(stderr,"Could not allocate space for strdup.");
+            exit(EXIT_FAILURE);
+        }
+        slow5_record -> read_id_len = strlen(slow5_record -> read_id);
+        slow5_record -> read_group = 0;
+        slow5_record -> digitisation = 4096.0;
+        slow5_record -> offset = 3.0+i;
+        slow5_record -> range = 10.0+i;
+        slow5_record -> sampling_rate = 4000.0;
+        slow5_record -> len_raw_signal = 10+i;
+        slow5_record -> raw_signal = malloc(sizeof(int16_t)*(10+i));
+        if(slow5_record->raw_signal == NULL){
+            fprintf(stderr,"Could not allocate space for raw signal.");
+            exit(EXIT_FAILURE);
+        }
+        for(int j=0;j<10+i;j++){
+            slow5_record->raw_signal[j] = j+i;
+        }
+
+    }
+
+    ret = slow5_write_batch(mt, read_batch,batch_size);
+
+    if(ret!=batch_size){
+        fprintf(stderr,"Writing failed\n");
+        exit(EXIT_FAILURE);
+    }
+
+    slow5_free_batch(read_batch);
+    slow5_free_mt(mt);
+    slow5_close(sf);
+
+    return 0;
+}
+```
 
-## SEE ALSO
 
diff --git a/docs/slow5_api/slow5_mt_api.md b/docs/slow5_api/slow5_mt_api.md
index 2cd34f3..6aacd4f 100755
--- a/docs/slow5_api/slow5_mt_api.md
+++ b/docs/slow5_api/slow5_mt_api.md
@@ -1,8 +1,8 @@
-# slow5lib Easy multi-thread API
+# slow5lib easy multi-thread API
 
 **NOTE: This API is in beta stage and the documentation is sparse. If something is not clear do not hesitate to open an [issue](https://github.com/hasindu2008/slow5lib/issues).**
 
-The easy multi-thread (called *mt* API) API allows the user to access SLOW5 using multiple threads, simply by specifying the number of threads, rather than needing to write their own multi-threading code. Note that this API is for your convenience, rather than for efficiency. It is not meant to be used by a programmer who has the expertise to write multi-threaded code and use the slow5 low-level API directly. While fetching using this API would be faster than using a single thread, it would not be as efficient as using low-level API functions directly from the programmer's own multi-threaded code.
+The easy multi-thread (called *mt* API) API allows the user to access SLOW5 files using multiple threads, simply by specifying the number of threads, rather than needing to write their own multi-threading code. This API is for programmer's convenience, rather than for efficiency. This API is not meant to be used by a programmer who has the expertise to write multi-threaded code and use the slow5 low-level API directly. While fetching using this API would be faster than using a single thread, it would not be as efficient as using low-level API functions directly from the programmer's own multi-threaded code.
 
 To use this API, include <slow5/slow5_mt.h> in your programme. Make sure to explicitly enable easy multi-thread API as `make slow5_mt=1`, during compile time of slow5lib.
 
@@ -43,7 +43,7 @@ typedef struct {
 * [slow5_get_next_batch](mt_api/slow5_get_next_batch.md)<br/>
   &nbsp;&nbsp;&nbsp;&nbsp;fetches the next batch of records at the current file pointer of a SLOW5 file
 * [slow5_get_batch](mt_api/slow5_get_batch.md)<br/>
-  &nbsp;&nbsp;&nbsp;&nbsp;fetches a batch of SLOW5 records corresponding to a given batch of read ID
+  &nbsp;&nbsp;&nbsp;&nbsp;fetches a batch of SLOW5 records corresponding to a given batch of read IDs
 
 
 ### Writing and editing
diff --git a/examples/mt/mt.c b/examples/mt/mt.c
index 470d202..cf58ab2 100644
--- a/examples/mt/mt.c
+++ b/examples/mt/mt.c
@@ -48,7 +48,7 @@ void sequential_read_func(){
             printf("%s\t%ld\n",rec[i]->read_id,len_raw_signal);
         }
 
-        if(ret<batch_size){ //this indicates nothing left to read //need to handle errors
+        if(ret<batch_size){ //this indicates nothing left to read //better handling of errors may be introduced in future
             break;
         }
     }
@@ -68,9 +68,11 @@ void random_read_func(){
        fprintf(stderr,"Error in opening file\n");
        exit(EXIT_FAILURE);
     }
+
     slow5_rec_t **rec = NULL;
+    int ret=0;
 
-    int ret = slow5_idx_load(sp);
+    ret = slow5_idx_load(sp);
     if(ret<0){
         fprintf(stderr,"Error in loading index\n");
         exit(EXIT_FAILURE);
@@ -86,18 +88,30 @@ void random_read_func(){
     rid[3]="read_id_4";
 
     slow5_mt_t *mt = slow5_init_mt(num_thread,sp);
+    if (mt==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising multi-thread struct\n");
+        exit(EXIT_FAILURE);
+    }
 
     slow5_batch_t *read_batch = slow5_init_batch(batch_size);
+    if (read_batch==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising slow5 record batch\n");
+        exit(EXIT_FAILURE);
+    }
 
     ret = slow5_get_batch(mt, read_batch, rid, num_rid);
-    assert(ret==num_rid);
+    if(ret!=num_rid){
+        fprintf(stderr,"Error in fetching all records\n");
+        exit(EXIT_FAILURE);
+    }
+
     for(int i=0;i<ret;i++){
         rec = read_batch->slow5_rec;
         uint64_t len_raw_signal = rec[i]->len_raw_signal;
         printf("%s\t%ld\n",rec[i]->read_id,len_raw_signal);
     }
-    slow5_free_batch(read_batch);
 
+    slow5_free_batch(read_batch);
     slow5_free_mt(mt);
 
     slow5_idx_unload(sp);
@@ -184,7 +198,17 @@ void write_func(){
     int num_thread = 8;
 
     slow5_mt_t *mt = slow5_init_mt(num_thread,sf);
+    if (mt==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising multi-thread struct\n");
+        exit(EXIT_FAILURE);
+    }
+
     slow5_batch_t *read_batch = slow5_init_batch(batch_size);
+    if (read_batch==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising slow5 record batch\n");
+        exit(EXIT_FAILURE);
+    }
+
     slow5_rec_t **rec = read_batch->slow5_rec;
 
     /******************* SLOW5 records ************************/
@@ -255,7 +279,7 @@ void write_func(){
 
     ret = slow5_write_batch(mt, read_batch,batch_size);
 
-    if(ret<batch_size){
+    if(ret!=batch_size){
         fprintf(stderr,"Writing failed\n");
         exit(EXIT_FAILURE);
     }
diff --git a/include/slow5/slow5_mt.h b/include/slow5/slow5_mt.h
index c8e84cd..51c66be 100644
--- a/include/slow5/slow5_mt.h
+++ b/include/slow5/slow5_mt.h
@@ -15,12 +15,10 @@ extern "C" {
 /**************** This API is still in beta stage, there could be bugs *************************/
 
 /*
-This is a multi-threading API that can fetch a batch of slow5 records using multiple threads in parallel.
-This API uses a fork-join thread model.
-It is not meant to be used by a programmer who has the expertise to write multi-threaded code and use the slow5 low-level API directly.
+This is a easy multi-thread API that can fetch a batch of slow5 records using multiple threads in parallel.
+This API uses a fork-join thread model. It is not meant to be used by a programmer who has the expertise to write multi-threaded code and use the slow5 low-level API directly.
 While fetching using this API would be faster than using a single thread, it would not be as efficient as using low-level API functions
-directly from the programmer's own multi-threaded code.
-This API can be optimised using a thread pool, but that is not implemented yet.
+directly from the programmer's own multi-threaded code. This API can be optimised using a thread pool, but that is not implemented yet.
 */
 
 /* a batch of read data (dynamic data based on the reads) */
@@ -52,10 +50,10 @@ also each batch call will create and destruct threads rather than using a thread
 
 slow5_mt_t *slow5_init_mt(int num_thread, slow5_file_t *s5p);
 slow5_batch_t* slow5_init_batch(int batch_capacity);
-int slow5_get_next_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int batch_size);
+int slow5_get_next_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int num_reads);
 int slow5_get_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, char **rid, int num_rid);
-int slow5_write_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int batch_size);
-int slow5_encode_batch(slow5_mt_t *core, slow5_batch_t *db, int batch_size); //used by slow5curl
+int slow5_write_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int num_reads);
+int slow5_encode_batch(slow5_mt_t *core, slow5_batch_t *db, int num_reads); //used by slow5curl
 void slow5_free_batch(slow5_batch_t *read_batch);
 void slow5_free_mt(slow5_mt_t *mt);
 
diff --git a/src/slow5_mt.c b/src/slow5_mt.c
index 5654556..f0c4623 100644
--- a/src/slow5_mt.c
+++ b/src/slow5_mt.c
@@ -83,11 +83,9 @@ slow5_batch_t* slow5_init_batch(int batch_capacity){
 /* load a data batch from disk */
 static int slow5_load_db(slow5_mt_t* core, slow5_batch_t* db) {
 
-    db->n_rec = 0;
-
     int32_t i = 0;
-    while (db->n_rec < db->capacity_rec) {
-        i=db->n_rec;
+    while (i < db->n_rec) {
+
         db->mem_records[i] = (char *)slow5_get_next_mem(&(db->mem_bytes[i]), core->sf);
 
         if (db->mem_records[i] == NULL) {
@@ -101,25 +99,22 @@ static int slow5_load_db(slow5_mt_t* core, slow5_batch_t* db) {
             }
         }
         else {
-            db->n_rec++;
+            i++;
         }
     }
 
-    return db->n_rec;
+    return i;
 }
 
 
 static int slow5_write_db(slow5_mt_t* core, slow5_batch_t* db) {
 
-
     int32_t i = 0;
     for(i=0;i<db->n_rec;i++) {
-
         size_t n = fwrite(db->mem_records[i], db->mem_bytes[i], 1, core->sf->fp);
         if (n != 1) {
             SLOW5_ERROR("Writing failed for read id %s!\n", db->slow5_rec[i]->read_id);
         }
-
     }
 
     return i;
@@ -323,68 +318,54 @@ static void slow5_work_db(slow5_mt_t* core, slow5_batch_t* db, void (*func)(slow
 
 int slow5_get_batch(slow5_mt_t *core, slow5_batch_t *db, char **rid, int num_rid){
 
-    //slow5_mt_t *core = slow5_init_core(s5p,num_rid,num_threads);
-    //slow5_batch_t* db = slow5_init_db(core);
+    if(num_rid>db->capacity_rec){
+        SLOW5_ERROR("Requested %d is greater than the capacity %d",num_rid,db->capacity_rec);
+        exit(EXIT_FAILURE);
+    }
 
     db->rid = rid;
     db->n_rec = num_rid;
     slow5_work_db(core,db,slow5_work_per_single_read2);
     SLOW5_LOG_DEBUG("loaded and parsed %d recs\n",num_rid);
-
-    //*read = db->slow5_rec;
-
     slow5_free_db_tmp(db);
-    // slow5_free_db(db);
-    // slow5_free_core(core);
 
     return num_rid;
 }
 
 
-int slow5_get_next_batch(slow5_mt_t *core, slow5_batch_t *db, int batch_size){
+int slow5_get_next_batch(slow5_mt_t *core, slow5_batch_t *db, int num_reads){
 
-    // slow5_mt_t *core = slow5_init_core(s5p,batch_size,num_threads);
-    // slow5_batch_t* db = slow5_init_db(core);
-    db->n_rec = batch_size;
-
-    int num_read=slow5_load_db(core,db);
-    SLOW5_LOG_DEBUG("Loaded %d recs\n",num_read);
+    if(num_reads>db->capacity_rec){
+        SLOW5_ERROR("Requested %d is greater than the capacity %d",num_reads,db->capacity_rec);
+        exit(EXIT_FAILURE);
+    }
+    db->n_rec = num_reads;
+    int n = slow5_load_db(core,db);
+    db->n_rec = n;
+    SLOW5_LOG_DEBUG("Loaded %d recs\n",n);
     slow5_work_db(core,db,slow5_work_per_single_read);
-    SLOW5_LOG_DEBUG("Parsed %d recs\n",num_read);
-
-    //*read = db->slow5_rec;
-
+    SLOW5_LOG_DEBUG("Parsed %d recs\n",n);
     slow5_free_db_tmp(db);
-    // slow5_free_db(db);
-    // slow5_free_core(core);
 
-    return num_read;
+    return n;
 }
 
-int slow5_encode_batch(slow5_mt_t *core, slow5_batch_t *db, int batch_size){
-    db->n_rec = batch_size;
+int slow5_encode_batch(slow5_mt_t *core, slow5_batch_t *db, int num_reads){
+    db->n_rec = num_reads;
     slow5_work_db(core,db,slow5_work_per_single_read3);
     return db->n_rec;
 }
 
-int slow5_write_batch(slow5_mt_t *core, slow5_batch_t *db, int batch_size){
-
-    // slow5_mt_t *core = slow5_init_core(s5p,batch_size,num_threads);
-    // slow5_batch_t* db = slow5_init_db(core);
+int slow5_write_batch(slow5_mt_t *core, slow5_batch_t *db, int num_reads){
 
-    db->n_rec = batch_size;
-    // free(db->slow5_rec); //stupid lazy for now
-    // db->slow5_rec = read;
+    db->n_rec = num_reads;
     slow5_work_db(core,db,slow5_work_per_single_read3);
-    SLOW5_LOG_DEBUG("Processed %d recs\n",batch_size);
+    SLOW5_LOG_DEBUG("Processed %d recs\n",num_reads);
 
     int num_wr=slow5_write_db(core,db);
     SLOW5_LOG_DEBUG("Written %d recs\n",num_wr);
 
-    // db->slow5_rec = NULL;
     slow5_free_db_tmp(db);
-    // slow5_free_db(db);
-    // slow5_free_core(core);
 
     return num_wr;
 }
@@ -498,7 +479,7 @@ slow5_batch_t* slow5_init_batch(int batch_capacity){
     fprintf(stderr,"slow5lib has not been compiled with lazy multithreading support\n");
     exit(EXIT_FAILURE);
 }
-int slow5_get_next_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int batch_size){
+int slow5_get_next_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int num_reads){
     fprintf(stderr,"slow5lib has not been compiled with lazy multithreading support\n");
     exit(EXIT_FAILURE);
 }
@@ -506,11 +487,11 @@ int slow5_get_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, char **rid, int n
     fprintf(stderr,"slow5lib has not been compiled with lazy multithreading support\n");
     exit(EXIT_FAILURE);
 }
-int slow5_encode_batch(slow5_mt_t *core, slow5_batch_t *db, int batch_size){
+int slow5_encode_batch(slow5_mt_t *core, slow5_batch_t *db, int num_reads){
     fprintf(stderr,"slow5lib has not been compiled with lazy multithreading support\n");
     exit(EXIT_FAILURE);
 }
-int slow5_write_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int batch_size){
+int slow5_write_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int num_reads){
     fprintf(stderr,"slow5lib has not been compiled with lazy multithreading support\n");
     exit(EXIT_FAILURE);
 }

From 2d46a280faa7bc827dc60b19f63041cae4b76bab Mon Sep 17 00:00:00 2001
From: Hasindu Gamaarachchi <hasindu2008@gmail.com>
Date: Sat, 18 Nov 2023 00:31:18 +1100
Subject: [PATCH 10/11] easy multithread API

---
 .github/workflows/c-cpp.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/c-cpp.yml b/.github/workflows/c-cpp.yml
index f8870da..83fb41c 100644
--- a/.github/workflows/c-cpp.yml
+++ b/.github/workflows/c-cpp.yml
@@ -118,6 +118,8 @@ jobs:
       run: make -j8
     - name: test-gcc
       run: make test
+    - name: make mt
+      run: examples/mt/build.sh
   os_x_11:
     name: OSX 11
     runs-on: macos-11

From e0d0d0f3da18374519b60924850c9e7f900a6bb3 Mon Sep 17 00:00:00 2001
From: Hasindu Gamaarachchi <hasindu2008@gmail.com>
Date: Sun, 19 Nov 2023 00:51:52 +1100
Subject: [PATCH 11/11] version 1.2.0-beta

---
 include/slow5/slow5_defs.h | 2 +-
 setup.py                   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/slow5/slow5_defs.h b/include/slow5/slow5_defs.h
index 800722a..845df54 100644
--- a/include/slow5/slow5_defs.h
+++ b/include/slow5/slow5_defs.h
@@ -44,7 +44,7 @@ The API documentation is available at https://hasindu2008.github.io/slow5tools/
 */
 
 // library version
-#define SLOW5_LIB_VERSION "1.1.0-dirty"
+#define SLOW5_LIB_VERSION "1.2.0-beta"
 
 // maximum file version supported by this library - independent of slow5 library version above
 // if updating change all 4 below
diff --git a/setup.py b/setup.py
index fd0ea49..f07ce03 100644
--- a/setup.py
+++ b/setup.py
@@ -89,7 +89,7 @@ def readme():
 
 setup(
     name = 'pyslow5',
-    version='1.1.0-dev',
+    version='1.2.0-beta',
     url = 'https://github.com/hasindu2008/slow5lib',
     description='slow5lib python bindings',
     long_description=readme(),