Add deprecation warnings to APIv1

* add runtime warnings to `make-thread` and `make-lock`
* add compile-time warnings as a compiler macro as well
* document briefly how to migrate to APIv2

apiv1/default-implementations.lisp

@@ -55,9 +55,14 @@ It is safe to call repeatedly."
     implementation-defined. Portable code should not depend on
     particular behaviour in this case, nor should it assign to such
     variables without first rebinding them in the new thread."
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (%make-thread (binding-default-specials function initial-bindings)
                 (or name "Anonymous thread")))
 
+(define-compiler-macro make-thread (&whole form)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
+  form)
+
 (defdfun %make-thread (function name)
   "The actual implementation-dependent function that creates threads."
   (declare (ignore function name))
@@ -101,6 +106,10 @@ It is safe to call repeatedly."
   (declare (ignore name))
   (list nil))
 
+(define-compiler-macro make-lock (&whole form)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
+  form)
+
 (defdfun acquire-lock (lock &optional wait-p)
   "Acquire the lock LOCK for the calling thread.
   WAIT-P governs what happens if the lock is not available: if WAIT-P

apiv1/impl-abcl.lisp

@@ -59,6 +59,7 @@ Distributed under the MIT license (see LICENSE file)
   (typep object 'mutex-recursive))
 
 (defun make-lock (&optional name)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (make-mutex 
    :name (or name "Anonymous lock")
    :lock (jnew "java.util.concurrent.locks.ReentrantLock")))

apiv1/impl-allegro.lisp

@@ -24,6 +24,7 @@ Distributed under the MIT license (see LICENSE file)
   (typep object 'mp:process-lock))
 
 (defun make-lock (&optional name)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (mp:make-process-lock :name (or name "Anonymous lock")))
 
 (defun make-recursive-lock (&optional name)

apiv1/impl-clasp.lisp

@@ -43,6 +43,7 @@ Distributed under the MIT license (see LICENSE file)
        (mp:recursive-lock-p object)))
 
 (defun make-lock (&optional name)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (mp:make-lock :name (or name :anonymous)))
 
 (defun acquire-lock (lock &optional (wait-p t))

apiv1/impl-clisp.lisp

@@ -41,6 +41,7 @@ Distributed under the MIT license (see LICENSE file)
        (mt:mutex-recursive-p object)))
 
 (defun make-lock (&optional name)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (mt:make-mutex :name (or name "Anonymous lock")))
 
 (defun acquire-lock (lock &optional (wait-p t))

apiv1/impl-clozure.lisp

@@ -41,6 +41,7 @@ Distributed under the MIT license (see LICENSE file)
   (typep object 'ccl:lock))
 
 (defun make-lock (&optional name)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (ccl:make-lock (or name "Anonymous lock")))
 
 (defun acquire-lock (lock &optional (wait-p t))

apiv1/impl-cmucl.lisp

@@ -51,6 +51,7 @@ Distributed under the MIT license (see LICENSE file)
   (typep object 'mp::recursive-lock))
 
 (defun make-lock (&optional name)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (mp:make-lock (or name "Anonymous lock")
                 :kind :error-check))
 

apiv1/impl-ecl.lisp

@@ -43,6 +43,7 @@ Distributed under the MIT license (see LICENSE file)
        (mp:recursive-lock-p object)))
 
 (defun make-lock (&optional name)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (mp:make-lock :name (or name "Anonymous lock")))
 
 (defun acquire-lock (lock &optional (wait-p t))

apiv1/impl-genera.lisp

@@ -39,6 +39,7 @@ Distributed under the MIT license (see LICENSE file)
   lock-argument)
 
 (defun make-lock (&optional name)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (let ((lock (process:make-lock (or name "Anonymous lock"))))
     (make-lock-internal :lock lock
                         :lock-argument nil)))

apiv1/impl-lispworks.lisp

@@ -62,6 +62,7 @@ Distributed under the MIT license (see LICENSE file)
        (mp:lock-recursive-p object)))
 
 (defun make-lock (&optional name)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (mp:make-lock :name (or name "Anonymous lock")
                 #-(or lispworks4 lispworks5) :recursivep
                 #-(or lispworks4 lispworks5) nil))

apiv1/impl-mcl.lisp

@@ -33,6 +33,7 @@ Distributed under the MIT license (see LICENSE file)
   (typep object 'ccl:lock))
 
 (defun make-lock (&optional name)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (ccl:make-lock (or name "Anonymous lock")))
 
 (defun acquire-lock (lock &optional (wait-p t))

apiv1/impl-mezzano.lisp

@@ -34,6 +34,7 @@ Distributed under the MIT license (see LICENSE file)
   (mezzano.supervisor:mutex-p object))
 
 (defun make-lock (&optional name)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (mezzano.supervisor:make-mutex name))
 
 (defun acquire-lock (lock &optional (wait-p t))

apiv1/impl-mkcl.lisp

@@ -41,6 +41,7 @@ Distributed under the MIT license (see LICENSE file)
        (mt:recursive-lock-p object)))
 
 (defun make-lock (&optional name)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (mt:make-lock :name (or name "Anonymous lock")))
 
 (defun acquire-lock (lock &optional (wait-p t))

apiv1/impl-sbcl.lisp

@@ -41,6 +41,7 @@ Distributed under the MIT license (see LICENSE file)
   (typep object 'sb-thread:mutex))
 
 (defun make-lock (&optional name)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (sb-thread:make-mutex :name (or name "Anonymous lock")))
 
 (defun acquire-lock (lock &optional (wait-p t))

apiv1/impl-scl.lisp

@@ -36,6 +36,7 @@ Distributed under the MIT license (see LICENSE file)
   (typep object 'thread:recursive-lock))
 
 (defun make-lock (&optional name)
+  (warn "Bordeaux-Threads APIv1 is deprecated. Please migrate to APIv2.")
   (thread:make-lock (or name "Anonymous lock")))
 
 (defun acquire-lock (lock &optional (wait-p t))

docs/content/_index.md

@@ -16,6 +16,15 @@ This document describes the second version of the API (APIv2), which
 differs from the first version in a few key points and aims to provide
 a more uniformous interface across all Common Lisp implementations.
 
+## Migration from APIv1 to APIv2
+
+APIv2 is mostly compatible with v1, and in most cases it should
+suffice to replace all references to package `bordeaux-threads` (or
+`bt`) with `bordeaux-threads-2` (or `bt2`).
+
+For more details, there's a [blog
+post](https://blog.cddr.org/posts/2023-05-27-bordeaux-threads-apiv2/).
+
 ## Host support
 
 When Bordeaux-Threads was created, most Common Lisp implementations