doc/threads.doc

   1 How to compile SSLeay for multi-threading.
   2
   3 Well basically it is quite simple, set the compiler flags and build.
   4 I have only really done much testing under Solaris and Windows NT.
   5 If you library supports localtime_r() and gmtime_r() add,
   6 -DTHREADS to the makefile parameters.  You can probably survive with out
   7 this define unless you are going to have multiple threads generating
   8 certificates at once.  It will not affect the SSL side of things.
   9
  10 The approach I have taken to doing locking is to make the application provide
  11 callbacks to perform locking and so that the SSLeay library can distinguish
  12 between threads (for the error state).
  13
  14 To have a look at an example program, 'cd mt; vi mttest.c'.
  15 To build under solaris, sh solaris.sh, for Windows NT or Windows 95,
  16 win32.bat
  17
  18 This will build mttest which will fire up 10 threads that talk SSL
  19 to each other 10 times.
  20 To enable everything to work, the application needs to call
  21
  22 CRYPTO_set_id_callback(id_function);
  23 CRYPTO_set_locking_callback(locking_function);
  24
  25 before any multithreading is started.
  26 id_function does not need to be defined under Windows NT or 95, the
  27 correct function will be called if it is not.  Under unix, getpid()
  28 is call if the id_callback is not defined, for solaris this is wrong
  29 (since threads id's are not pid's) but under IRIX it is correct
  30 (threads are just processes sharing the data segement).
  31
  32 The locking_callback is used to perform locking by the SSLeay library.
  33 eg.
  34
  35 void solaris_locking_callback(mode,type,file,line)
  36 int mode;
  37 int type;
  38 char *file;
  39 int line;
  40         {
  41         if (mode & CRYPTO_LOCK)
  42                 mutex_lock(&(lock_cs[type]));
  43         else
  44                 mutex_unlock(&(lock_cs[type]));
  45         }
  46
  47 Now in this case I have used mutexes instead of read/write locks, since they
  48 are faster and there are not many read locks in SSLeay, you may as well
  49 always use write locks.  file and line are __FILE__ and __LINE__ from
  50 the compile and can be usefull when debugging.
  51
  52 Now as you can see, 'type' can be one of a range of values, these values are
  53 defined in crypto/crypto.h
  54 CRYPTO_get_lock_name(type) will return a text version of what the lock is.
  55 There are CRYPTO_NUM_LOCKS locks required, so under solaris, the setup
  56 for multi-threading can be
  57
  58 static mutex_t lock_cs[CRYPTO_NUM_LOCKS];
  59
  60 void thread_setup()
  61         {
  62         int i;
  63
  64         for (i=0; i<CRYPTO_NUM_LOCKS; i++)
  65                 mutex_init(&(lock_cs[i]),USYNC_THREAD,NULL);
  66         CRYPTO_set_id_callback((unsigned long (*)())solaris_thread_id);
  67         CRYPTO_set_locking_callback((void (*)())solaris_locking_callback);
  68         }
  69
  70 As a final note, under Windows NT or Windows 95, you have to be careful
  71 not to mix the various threaded, unthreaded and debug libraries.
  72 Normally if they are mixed incorrectly, mttest will crash just after printing
  73 out some usage statistics at the end.  This is because the
  74 different system libraries use different malloc routines and if
  75 data is malloc()ed inside crypt32.dll or ssl32.dll and then free()ed by a
  76 different library malloc, things get very confused.
  77
  78 The default SSLeay DLL builds use /MD, so if you use this on your
  79 application, things will work as expected.  If you use /MDd,
  80 you will probably have to rebuild SSLeay using this flag.
  81 I should modify util/mk1mf.pl so it does all this correctly, but
  82 this has not been done yet.
  83
  84 One last warning.  Because locking overheads are actually quite large, the
  85 statistics collected against the SSL_CTX for successfull connections etc
  86 are not locked when updated.  This does make it possible for these
  87 values to be slightly lower than they should be, if you are
  88 running multithreaded on a multi-processor box, but this does not really
  89 matter much.
  90