Proposal: libsmbclient API

[Derrell Lipman]

On Tue, Mar 24, 2009 at 10:13 AM, Andreas Schneider <mail at cynapses.org>wrote:

> On Tuesday 24 March 2009 14:06:38 you wrote:
> > Hi Andreas,
>
> Hi Derrell,
>
> > I've reviewed your provided attachments. Unless I'm missing something, it
> > seems that the only real substantive change is a per-context errno value.
> > Am I reading that correctly?
>
> the plan is to get rid of the static context and all global variables. This
> will be the easiest way to make libsmbclient thread-safe, pass the context
> to
> every function.


No, that's a problem. We can't do what you're proposing, but I think you
have a misconception about the library. There are TWO separate interfaces to
libsmbclient. The one you're referring to with the static context is for
single-threaded applications only, and is the simple, posix-like interface.
At one level below that is the to-be-thread-safe interface where a context
is (already) passed to each function. The former will never be thread-safe
by definition because it uses a static context, but is the interface most
commonly in use right now by applications. The latter is already nearly
thread-safe, with only a few changes required (e.g. errno) to make it so. It
is only this latter interface that should change at all, and only so much as
is necessary.

>
>
> > As to the separation of the options, do you envision having multiple sets
> > of options? I can't really see that as a common requirement, so it seems
> > cleaner to me to keep the options in the context structure itself, but
> > cleanliness is a matter of personal preference. :-) Personal preference
> not
> > withstanding, though, I believe that we can do all changes to
> libsmbclient
> > in a backward-compatible fashion, and that should be a major goal of this
> > project. There are many (non-threaded) applications already written that
> > should continue to work without change. The API should change only where
> > absolutely necessary to meet the new goals.
>
> Well I think you can create a struct in the smbc_context_s too. I would
> prefer
> it this way. I think it makes it more clear that the options are separate
> from
> the context. I'm sure we will find a way which will suit everyone.


I agree, it would be nice if all of the options were held in a separate
struct within the private portion of the context. Unfortunately, again for
backwards compatibility, some fields remain in the public portion of the
context and all newer fields have moved to the private portion. This is for
ABI compatibility.

 > As an example of the type of backward-compatible change I propose... You
> > pointed out that errno is not thread safe in many environments. There
> are,
> > however, non-threaded applications depending on looking at errno so they
> > should continue to be able to do so. To solve both issues, and assuming
> the
> > addition of a smbc_set_errno() function like you propose, we can change
> all
> > of the internal code to call smbc_set_errno() instead of assigning to
> errno
> > directly, but smbc_set_errno() should assign to errno in addition to
> > assigning to the context-specific errno member. Non-threaded (existing)
> > applications then continue to operate as they do currently and can
> retrieve
> > errno, and new, threaded applications, can make use of the
> smbc_get_errno()
> > function to retrieve the thread- or more accurately, context-specific
> errno
> > value.
> >
> > Sound reasonable?
>
> I've changed nearly every function in the header files to break the
> backward-
> compatibility by intention. I've tried to create sane names and uses names
> that make clear what the function does. Nearly everything changes in master
> so
> I think we should start with a cleaned up API for libsmbclient.


Well the samba3 portion of master isn't changing, and needs to retain
backwards compatibility. I think we can solve all of these issues, though,
by having this be the beginnings of a samba4 libsmbclient. A libsmbclient
for samba4 will have a much cleaner interface to the internals, due to the
benefit of 20-20-hindsight of some of the troubles in samba3 leading towards
a very clean interface design from the outset.  It can, as well, address
(remove!) many of the historical dependencies that samba3's libsmbclient has
had to live with.

>
> Will you be at SambaXP?
>

Unfortunately not. That isn't in the cards right now. :-(

Derrell