A level of preprocessor indirection lets us later change the implementation if
desired.

llexception_test.cpp is an unusual test source in that it need not be verified
on every build, so its invocation in indra/llcommon/CMakeLists.txt is
commented out with that remark. Its purpose is to help a developer decide what
base class(es) to use for LLException, how to throw and how to catch.

Our current conclusions are written up as comments in llexception_test.cpp.

Added CRASH_ON_UNHANDLED_EXCEPTION() and LOG_UNHANDLED_EXCEPTION() macros to
llexception.h -- macros to log __FILE__, __LINE__ and __PRETTY_FUNCTION__ of
the catch site. These invoke functions in llexception.cpp so we don't need to
#include llerror.h for every possible catch site.

The only call to the findDiscardLevelsBoundaries() method was commented out
inside initDecode(), with a comment:
        // Merov : Test!! DO NOT COMMIT!!

This was the only caller of copy_tile(), which was the only caller of
copy_block(). Commented out all three of these (biggish!) functions, since I
have no idea what any of them were supposed to do or when it might be useful
to call them. In other words, I can't yet rule out the possibility that I
might have to uncomment them.

Use boost::scoped_ptr instead of raw pointers to LLKDUMemSource,
LLKDUDecodeState, kdu_coords and kdu_dims so cleanup is simpler, and automated
on destruction of LLImageJ2CKDU.

Replace pointer to kdu_codestream with a custom RAII class. kdu_codestream is
itself an opaque handle, so we don't need to add another layer of indirection.
Just wrap it to ensure its destroy() method is reliably called when needed.

Make static instances of LLKDUMessageWarning and LLKDUMessageError
self-register, eliminating the companion static bool and explicit checks in
code.

instead of legacy BOOL.

Derive them both from a common base class that does the message logging,
instead of having each handler class log redundantly -- especially since the
put_text() override accepting const kdu_uint16* was simply streaming the
kdu_uint16 pointer to the log file, which would log the hex value of the
pointer.

Although we want a static instance of each of these handler classes, pull it
out rather than nesting the instance within the class itself.

Specifically, remove unused function pointer types CreateLLImageJ2CFunction,
DestroyLLImageJ2CFunction and EngineInfoLLImageJ2CFunction.

Also eliminate static fallbackDestroyLLImageJ2CImpl() and
fallbackEngineInfoLLImageJ2CImpl(), leaving only static
fallbackCreateLLImageJ2CImpl().

We do need a factory function to instantiate the appropriate LLImageJ2CImpl
subclass, so leave the fallbackCreateLLImageJ2CImpl() link seam in place.

However, given that every known LLImageJ2CImpl subclass is cheap to
instantiate, make getEngineInfo() a pure virtual method on that subclass: the
static LLImageJ2C::getEngineInfo() method can temporarily construct an
instance to query. While we're at it, make getEngineInfo() return std::string
like LLImageJ2C::getEngineInfo(). It's ridiculous that
fallbackEngineInfoLLImageJ2CImpl() implementations constructed a static
std::string and returned its c_str(), only to have LLImageJ2C::getEngineInfo()
construct ANOTHER std::string from the returned const char*.

fallbackDestroyLLImageJ2CImpl() never did anything useful: it merely deleted
the passed LLImageJ2CImpl subclass pointer as the specific subclass type. But
since LLImageJ2CImpl's destructor is virtual, LLImageJ2C's destructor could
simply delete the stored LLImageJ2CImpl*. In fact, make mImpl a
boost::scoped_ptr<LLImageJ2CImpl> so we don't even have to delete it manually.

destroyLLImageJ2CKDU().

These were apparently intended as simple C-style DLL entry points. But as
nobody calls them, and as we decided against building the viewer from DLLs,
they only clutter the code.

This also introduces LLContinueError for exceptions which should interrupt
some part of viewer processing (e.g. the current coroutine) but should attempt
to let the viewer session proceed.

Derive all existing viewer exception classes from LLException rather than from
std::runtime_error or std::logic_error.

Use BOOST_THROW_EXCEPTION() rather than plain 'throw' to enrich the thrown
exception with source file, line number and containing function.

The LLProtectedDataException and LLCertException exception classes didn't used
to be derived from std::exception, so they followed their own getMessage()
convention instead of the standard what() convention. Now that they're derived
from std::exception, remove getMessage() and change its few consumers to use
what() instead. Thanks NickyD for suggesting.

Also getCert().

Also LLProtectedDataException::getMessage().

Also place KDUError into anonymous namespace to emphasize that it's entirely
local to this .cpp file.

http://en.cppreference.com/w/cpp/language/throw says of the plain throw syntax:

"This form is only allowed when an exception is presently being handled (it
calls std::terminate if used otherwise)."

On advice from Oz, replace plain 'throw;' with throwing a std::runtime_error.

KduError is derived from std::runtime_error, so the message string becomes its
what() message.

whose body reads:

    // *FIX: This exception is bad, bad, bad. It gets thrown from a
    // destructor which can lead to immediate program termination!
    throw "ll_kdu_error() throwing an exception";

which would be bad indeed... if ll_kdu_error() were ever actually referenced
by anything!

derived from std::runtime_error.

In particular:
NotImplemented in llhttpnode.cpp
RelocateError in llupdateinstaller.cpp
LLProtectedDataException, LLCertException and subclasses in llsecapi.h

Had to add no-throw destructor overrides to LLCertException and subclasses
because otherwise clang complains that the implicitly-generated destructor's
exception specification is more lax than the base class's.

MAINT-6565: Grab a shared pointer and encapsulate it into the bind call in place of this. Ensures that the impl is not deleted while the coroutine is active.

The LLApp API used to consist of init(), mainLoop(), cleanup() methods. This
makes sense -- but on Mac that structure was being subverted. The method
called mainLoop() was in fact being called once per frame. There was
initialization code in the method, which (on Mac) needed to be skipped with an
already-initialized bool. There was a 'while' loop which (on Mac) needed to be
turned into an 'if' instead so the method would return after every frame.

Rename LLApp::mainLoop() to frame(). Propagate through subclasses LLAppViewer
and LLCrashLogger. Document the fact that frame() returns true to mean "done."
(This was always the case, but had to be inferred from the code.)

Rename the Mac Objective-C function mainLoop to oneFrame. Rename the C++ free
function it calls from runMainLoop() to pumpMainLoop(). Add comments to
llappdelegate-objc.mm explaining (inferred) control flow.

Change the Linux viewer main() and the Windows viewer WINMAIN() from a single
LLAppViewer::mainLoop() call to repeatedly call frame() until it returns true.

Move initialization code from the top of LLAppViewer::frame() to the init()
method, where it more properly belongs. Remove corresponding
mMainLoopInitialized flag (and all references) from LLAppViewer.

Remove 'while (! LLApp::isExiting())' (or on Mac, 'if (! LLApp::isExiting())')
from LLAppViewer::frame() -- thus unindenting the whole body of the 'while'
and causing many lines of apparent change. (Apologies to reviewers.)

There are four LLApp states: APP_STATUS_RUNNING, APP_STATUS_QUITTING,
APP_STATUS_STOPPED and APP_STATUS_ERROR. Change LLAppViewer::frame() return
value from (isExiting()) (QUITTING or ERROR) to (! isRunning()). I do not know
under what circumstances the state might transition to STOPPED during a
frame() call, but I'm quite sure that if it does, we don't want to call
frame() again. We only want a subsequent call if the state is RUNNING.

Also rename mainLoop() method in LLCrashLogger subclasses
LLCrashLoggerWindows, LLCrashLoggerMac, LLCrashLoggerLinux. Of course it's
completely up to the frame() method whether to yield control; none of those in
fact do. Honor protocol by returning true (frame() is done), even though each
one's main() caller ignores the return value.

In fact LLCrashLoggerWindows::mainLoop() wasn't using the return protocol
correctly anyway, returning wParam or 0 or 1 -- possibly because the return
protocol was never explicitly documented. It should always return true: "I'm
done, don't call me again."