Merge d74390a into 9bdaffc

doc.go

@@ -108,5 +108,12 @@ call RegisterFunction from ConnectHook.
 
 See the documentation of RegisterFunc for more details.
 
+Cgo SQLite3 Extensions
+
+Go callbacks are convenient, but the runtime overhead of reflecting
+incoming types can be significant.  For performance-critical
+functions, Cgo functions can also be defined.  See SQLiteConn's Raw
+method for an example.
+
 */
 package sqlite3

sqlite3.go

@@ -745,6 +745,45 @@ func (c *SQLiteConn) RegisterAggregator(name string, impl interface{}, pure bool
 	return nil
 }
 
+// Raw provides access to the underlying raw C sqlite context pointer
+// by casting the `raw` argument from `unsafe.Pointer` to
+// `*C.sqlite3`.  This is can be used, for example, to add your own C
+// functions directly (which, due to fewer runtime reflection checks,
+// typically run an order of magnitude faster).  For example:
+//
+//    /*
+//    #include <sqlite3.h>
+//    ...
+//    void myFunc(sqlite3_context *context, int argc, sqlite3_value **argv) {
+//        // Function definition
+//    }
+//
+//    int myfunc_setup(sqlite3 *db) {
+//        return sqlite3_create_function(db, "myFunc", ...);
+//    }
+//    */
+//    import "C"
+//
+//    d := &sqlite3.SQLiteDriver{
+//        ConnectHook: func(c *SQLiteConn) error {
+//            return c.Raw(func(raw unsafe.Pointer) error {
+//                db := (*C.sqlite3)(raw)
+//                if rv := C.myfunc_setup(db); rv != C.SQLITE_OK {
+//                    return sqlite3.ErrNo(rv)
+//                }
+//                return nil
+//            }
+//         },
+//    }
+//
+// Note that as of 1.13, go doesn't correctly handle passing C
+// function pointers back to C functions, so C.sqlite3_create_function
+// can't be called from Go directly.  See
+// https://github.com/golang/go/issues/19835 for more details.
+func (c *SQLiteConn) Raw(cb func(raw unsafe.Pointer) error) error {
+	return cb(unsafe.Pointer(c.db))
+}
+
 // AutoCommit return which currently auto commit or not.
 func (c *SQLiteConn) AutoCommit() bool {
 	c.mu.Lock()