NAME

       libdlm - dlm_get_fd, dlm_dispatch, dlm_pthread_init, dlm_ls_pthread_init, dlm_cleanup

SYNOPSIS

       #include <libdlm.h>
       int dlm_pthread_init();
       int dlm_ls_pthread_init(dlm_lshandle_t lockspace);
       int dlm_pthread_cleanup();
       int dlm_get_fd(void);
       int dlm_dispatch(int fd);

       link with -ldlm

DESCRIPTION

       libdlm provides the programmatic userspace interface to the Distributed Lock manager. It provides all the
       calls you need to manipulate locks & lockspaces
       libdlm can be used in pthread or non-pthread applications.  For  pthread  applications  simply  call  the
       following  function  before  doing  any  lock  operations.  If  you're using pthreads, remember to define
       _REENTRANT at the top of the program or using -D_REENTRANT on the compile line.
       pthreads is the normal way of using the DLM. This way you simply initialize the DLM's thread and all  the
       AST routines will be delivered in that thread. You just call the dlm_lock() etc routines in the main line
       of your program.
       If you don't want to use pthreads or you want to handle the dlm callback ASTs yourself then you  can  get
       an  FD  handle  to the DLM device and call dlm_dispatch() on it whenever it becomes active. That was ASTs
       will be delivered in the context of the thread/process that called dlm_dispatch().

   int dlm_pthread_init()
       Creates a thread to receive all lock ASTs. The AST callback function for lock operations will  be  called
       in  the  context  of  this  thread.  If there is a potential for local resource access conflicts you must
       provide your own pthread-based locking in the AST routine.

   int dlm_ls_pthread_init(dlm_lshandle_t lockspace)
       As dlm_pthread_init but initializes a thread for the specified lockspace.

   int dlm_pthread_cleanup()
       Cleans up the default lockspace threads after use. Normally you don't need  to  call  this,  but  if  the
       locking code is in a dynamically loadable shared library this will probably be necessary.
       For  non-pthread  based  applications  the  DLM provides a file descriptor that the program can feed into
       poll/select. If activity is detected on that FD then a dispatch function should be called:

   int dlm_get_fd()
       Returns a file-descriptor for the DLM suitable for passing in to poll() or select().

   int dlm_dispatch(int fd)
       Reads from the DLM and calls any AST routines that may be needed. This routine runs in the context of the
       caller so no extra locking is needed to protect local resources.

libdlm_lt

       There  also  exists  a "light" version of the libdlm library called libdlm_lt. This is provided for those
       applications that do not want to use pthread functions. If you use this library it is important that your
       application is NOT compiled with -D_REENTRANT or linked with libpthread.

EXAMPLES

       Create a lockspace and start a thread to deliver its callbacks:
       dlm_lshandle_t ls;

       ls = dlm_create_lockspace("myLS", 0660);
       dlm_ls_pthread_init(ls);

        ...

       status = dlm_ls_lock(ls,
                            ... );

        Using poll(2) to wait for and dispatch ASTs

       static int poll_for_ast(dlm_lshandle_t ls)
       {
           struct pollfd pfd;

           pfd.fd = dlm_ls_get_fd(ls);
           pfd.events = POLLIN;
           while (!ast_called)
           {
               if (poll(&pfd, 1, 0) < 0)
               {
                   perror("poll");
                   return -1;
               }
               dlm_dispatch(dlm_ls_get_fd(ls));
           }
           ast_called = 0;
           return 0;
       }

SEE ALSO

       libdlm(3),      dlm_lock(3),      dlm_unlock(3),      dlm_open_lockspace(3),     dlm_create_lockspace(3),
       dlm_close_lockspace(3), dlm_release_lockspace(3)