firebird/firebird-mirror
firebird/firebird-mirror
8
0
Fork 1
mirror of https://github.com/FirebirdSQL/firebird.git synced 2025-01-22 20:43:02 +01:00
Code Issues

Misc.

Browse Source
This commit is contained in:
asfernandes 2013-06-17 01:32:09 +00:00
parent 91e0c3af00
commit bee1797802
2 changed files with 23 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
doc/README.interfaces.html
View File

@ -20,7 +20,7 @@ oriented API.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Why did we decide to add a
new API in firebird 3? There was not single reason for it. May be the
new API in Firebird 3? There was not single reason for it. May be the
first one is limited to 16 bit size of very many integers (for
example - message size, SQL operator length, portion of BLOB data) in
existing API. This probably was enough when that API was introduced &ndash;
@ -38,7 +38,7 @@ that moment with at the same time great need in 64 bit counters.</FONT></P>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>The second reason is not
so clear from the first look but it's also important. It comes from
old times when firebird's predecessor did not support SQL &ndash;
old times when Firebird's predecessor did not support SQL &ndash;
another language was used to manage databases (you may get an idea
what it was reading QLI's help). Data was delivered between client
and server using messages with format defined at request compilation
@ -58,7 +58,7 @@ of data and there format making it formally possible to change
between fetch calls not only location but format too causing need in
BLR in each message-based fetch call. And to finish with this &ndash;
changing data format between fetches was broken at network layer in
pre-firebird times. </FONT>
pre-Firebird times. </FONT>
</P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
@ -80,18 +80,18 @@ how interfaces help to use messages API easily and comfortably.</FONT></P>
software it's always desired to avoid loose of performance. And it
was performance issues that caused the choice of interfaces not
compatible with COM. To describe them I need to say a few words
about providers architecture of firebird. The central part of it is
about providers architecture of Firebird. The central part of it is
YValve, which is aimed on dispatching API call to correct provider,
including old providers that potentially have older interfaces than
current one. That means that to make sure that provider really has
some new API method we must (when using COM) call IUnknown method for
each fetch call. Taken together with the fact that new API calls are
sometimes added to optimize performance COM-based solution looks bad
for future firebird versions.</FONT></P>
for future Firebird versions.</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Unlike COM, firebird
interfaces support multiple versions. Version of firebird interface
<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Unlike COM, Firebird
interfaces support multiple versions. Version of Firebird interface
is defined in a rather native manner &ndash; it's a total number of
virtual functions in interface. And version of interface may be
upgraded! That does not mean that one gets full new functionality:
@ -114,7 +114,7 @@ use non-COM interfaces it's good to notice that use of reference
counted interfaces in all cases is often an extra overhead. Some
interfaces have by definition unlimited lifetime (like IMaster &ndash;
main interfaces calling which functions one gets access to all the
rest of firebird API), others &ndash; API strictly defined by
rest of Firebird API), others &ndash; API strictly defined by
lifetime of parent interface, and for not multi-threaded things like
IStatus it's better to have simpler way to destroy it, i.e. dispose()
function.</FONT></P>
@ -147,7 +147,7 @@ interface, but this is not a requirement). </SPAN></FONT>
</P>
<P LANG="en" STYLE="margin-bottom: 0in"><FONT SIZE=4>To finish with
general interfaces hierarchy is IProvider, a kind of 'main' plugin in
firebird API. IProvider is derived from IPlugin and implemented by
Firebird API. IProvider is derived from IPlugin and implemented by
any provider (i.e. if you want to write your own provider you must
implement IProvider) and also implemented by YValve. It's
implementation from YValve which is returned to the user when
@ -179,7 +179,7 @@ difference with COM approach is that upgrade performed for interface
only once, after it's creation, but IUnknown methods must be called
each time we are going to call an interface with unknown version (or
that version should be stored separately and later checked). For once
upgraded firebird interface there is absolutely no waste of time when
upgraded Firebird interface there is absolutely no waste of time when
performing calls to it during all it's lifetime.</FONT></P>
<P LANG="en" STYLE="margin-bottom: 0in"><BR>
</P>

22
doc/README.providers.html
View File

@ -18,10 +18,10 @@
<P STYLE="text-indent: 0.39in; margin-bottom: 0in"><BR>
</P>
<P STYLE="text-indent: 0.39in; margin-bottom: 0in"><FONT SIZE=4>Providers
architecture is definitely one of key features of firebird 3. But to
architecture is definitely one of key features of Firebird 3. But to
be precise this is far not new feature - providers existed in
firebird's predecessors long ago, and in 'deeply hidden' form are
present in any firebird version. Initially providers were introduced
Firebird's predecessors long ago, and in 'deeply hidden' form are
present in any Firebird version. Initially providers were introduced
to deal with a task which is currently well known to be performed by
ODBC, ADO, BDE, etc. They were needed to make it possible to access
different database engines using single external interface. But later
@ -29,7 +29,7 @@ providers architecture (known that time as OSRI - Open Systems
Relational Interface) also showed itself as very efficient for
supporting mix of old and new database formats (different major ODS)
at single server and having mixed connections to local and remote
databases. Implemented in firebird 3 providers make it possible to
databases. Implemented in Firebird 3 providers make it possible to
support all this modes (remote connections, different ODS databases,
foreign engines) and also providers chaining (when some provider is
using callback to standard API when performig an operation on
@ -91,9 +91,9 @@ from 8 to 11) format databases. Removing old ODS support from engine
helps to make it's code simpler and a bit faster. Taking into an
account that this faster sometimes takes place in performance
critical places (like search of a key in an index block) avoiding old
code and related branches makes firebird work really faster.
code and related branches makes Firebird work really faster.
Providers architecture at the same time makes it possible to access
old databases when changing firebird version.</FONT></P>
old databases when changing Firebird version.</FONT></P>
<P STYLE="text-indent: 0.39in; margin-bottom: 0in"><FONT SIZE=4>The
strong feature of providers architecture is ability for user to add
his own providers to server and/or client. You may be surprised &ndash;
@ -132,7 +132,7 @@ BTW, same technique may be used at client too.</FONT></P>
access foreign DB engines using providers. This looks strange at the
first glance when a lot of other tools performing this task already
exist. But let's take into an account ability to access other
firebird databases using EXECUTE STATEMENT. With provider to ODBC or
Firebird databases using EXECUTE STATEMENT. With provider to ODBC or
other common tool to access various data sources it's getting
possible to directly access from procedures and triggers (using
mentioned EXECUTE STATEMENT) data from almost any database, at least
@ -142,10 +142,10 @@ engine if one wants to avoid ODBC layer for some reason. </FONT>
</P>
<P STYLE="text-indent: 0.39in; margin-bottom: 0in; font-style: normal">
<FONT SIZE=4>Description of how to access databases using providers
API is present in the interfaces part of firebird examples and
API is present in the interfaces part of Firebird examples and
therefore there is no need repeating it here. Moreover, except
IStatement (interface used for execution of SQL operators) and
IEvents (works with firebird events) all functions in interfaces are
IEvents (works with Firebird events) all functions in interfaces are
similar to old API.</FONT></P>
<P STYLE="text-indent: 0.39in; margin-bottom: 0in"><BR>
</P>
@ -154,10 +154,10 @@ similar to old API.</FONT></P>
<FONT SIZE=4>Q. Interfaces and providers are probably very good, but
I have old task written using plain functions API and for a lot of
reasons I can't rewrite it in the nearest future. Does it mean I have
problem migrating to firebird 3?</FONT></P>
problem migrating to Firebird 3?</FONT></P>
<P STYLE="text-indent: 0.39in; margin-bottom: 0in; font-style: normal">
<FONT SIZE=4>A. Definitely no problems. Old API is supported for
backward compatibility in firebird 3 and will be supported in future
backward compatibility in Firebird 3 and will be supported in future
versions as long as people need it.</FONT></P>
<P STYLE="text-indent: 0.39in; margin-bottom: 0in; font-style: normal">
<FONT SIZE=4>Q. And what about performance when using old API?</FONT></P>