is it necessary to call pthread_mutex_destroy on a mutex?

Question

I am using pthread_mutex_t in a C++ program, as follows:

class Mutex : public noncopyable
{
public:
    Mutex()
    {
        pthread_mutex_init(&m_mutex, NULL);
    }

    void acquire()
    {
        pthread_mutex_lock(&m_mutex);
    }

    void release()
    {
        pthread_mutex_unlock(&m_mutex);
    }

private:
    pthread_mutex_t m_mutex;
};

(The class is not copyable - http://www.boost.org/doc/libs/1_53_0/boost/noncopyable.hpp)

The thing that I don't understand - is it considered an error to not call pthread_mutex_destroy in the destructor? The documentation I have read does not state that destroy must be called.

Does anyone know, what does pthread_mutex_destroy actually do and under what conditions is it required?

EDIT

Does the answer for pthread_mutex_destroy also apply to pthread_cond_destroy, etc? They seem almost like useless functions to me, unless pthread_mutex_init et. al. are allocating memory? (the docs, to me, aren't entirely clear on this.)

It doesn't hurt me to call destroy anyway, so the question is largely academic.

On linux anyway, it seems destroy only sets the mutex to an invalid state:

int
__pthread_mutex_destroy (mutex)
     pthread_mutex_t *mutex;
{
  if ((mutex->__data.__kind & PTHREAD_MUTEX_ROBUST_NORMAL_NP) == 0
      && mutex->__data.__nusers != 0)
    return EBUSY;

  /* Set to an invalid value.  */
  mutex->__data.__kind = -1;

  return 0;
}

(From glibc-2.14/nptl/pthread_mutex_destroy.c).

Answer 1

If someone provides you with a destroy function, then you are required to call it as the final action on that object before it goes out of scope.

On architectures and implementations where the API has no effect, this will be optimised away, however if the API changes in future to require cleaning up of internal state and your code does not call it, your code will now have a memory and/or resource leak.

So the simple answer is yes; you must call this API - and here's the thing - even if the API does nothing at the moment, because although the API itself is fixed forever into the future, the implementation behind the API is not.