# translation of artsbuilder_detail.po to 
# translation of artsbuilder_detail.po to
# translation of artsbuilder_detail.po to
# Copyright (C) 2002 Free Software Foundation, Inc.
# Lwandle Mgidlana <lwandle@translate.org.za>, 2002
#
msgid ""
msgstr ""
"Project-Id-Version: artsbuilder_detail\n"
"POT-Creation-Date: 2001-02-09 01:25+0100\n"
"PO-Revision-Date: 2002-09-26 12:33+0200\n"
"Last-Translator: Lwandle Mgidlana <lwandle@translate.org.za>\n"
"Language-Team:  <xh@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: application/x-xml2pot; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"X-Generator: KBabel 1.0beta2\n"

#: index.docbook:7
#, no-c-format
msgid "&arts; in Detail"
msgstr ""

#: index.docbook:10
#, no-c-format
msgid "Architecture"
msgstr ""

#: index.docbook:12
#, no-c-format
msgid "The &arts; structure."
msgstr ""

#: index.docbook:21
#, no-c-format
msgid "Modules &amp; Ports"
msgstr ""

#: index.docbook:23
#, no-c-format
msgid ""
"The idea of &arts; is, that synthesis can be done using small modules, which "
"only do one thing, and then recombine them in complex structures. The small "
"modules normally have inputs, where they can get some signals or parameters, "
"and outputs, where they produce some signals."
msgstr ""

#: index.docbook:31
#, no-c-format
msgid ""
"One module (Synth&lowbar;ADD) for instance just takes the two signals at "
"it's input and adds them together. The result is available as output signal. "
"The places where modules provide their input/output signals are called ports."
msgstr ""

#: index.docbook:41
#, no-c-format
msgid "Structures"
msgstr "Izakhiwo"

#: index.docbook:43
#, no-c-format
msgid ""
"A structure is a combination of connected modules, some of which may have "
"parameters coded directly to their input ports, others which may be "
"connected, and others, which are not connected at all."
msgstr ""

#: index.docbook:49
#, no-c-format
msgid ""
"What you can do with &artsbuilder; is describing structures. You describe, "
"which modules you want to be connected with which other modules. When you "
"are done, you can save that structure description to a file, or tell &arts; "
"to create such a structure you described (Execute)."
msgstr ""

#: index.docbook:56
#, no-c-format
msgid "Then you'll probably hear some sound, if you did everything the right way."
msgstr ""

#: index.docbook:73
#, no-c-format
msgid "Latency"
msgstr ""

#: index.docbook:76
#, no-c-format
msgid "What Is Latency?"
msgstr ""

#: index.docbook:78
#, no-c-format
msgid ""
"Suppose you have an application called <quote>mousepling</quote>"
"(that should make a <quote>pling</quote>"
" sound if you click on a button. The latency is the time between your finger "
"clicking the mouse button and you hearing the pling. The latency in this "
"setup composes itself out of certain latencies, that have different causes."
msgstr ""

#: index.docbook:89
#, no-c-format
msgid "Latency in Simple Applications"
msgstr ""

#: index.docbook:91
#, no-c-format
msgid "In this simple application, latency occurs at these places:"
msgstr ""

#: index.docbook:95
#, no-c-format
msgid ""
"The time until the kernel has notified the X11 server that a mouse button "
"was pressed."
msgstr ""

#: index.docbook:95
#, no-c-format
msgid ""
"The time until the X11 server has notified your application that a mouse "
"button was pressed."
msgstr ""

#: index.docbook:95
#, no-c-format
msgid ""
"The time until the mousepling application has decided that this button is "
"worth playing a pling."
msgstr ""

#: index.docbook:95
#, no-c-format
msgid ""
"The time it takes the mousepling application to tell the soundserver that it "
"should play a pling."
msgstr ""

#: index.docbook:95
#, no-c-format
msgid ""
"The time it takes for the pling (which the soundserver starts mixing to the "
"other output at once) to go through the buffered data, until it really "
"reaches the position where the soundcard plays."
msgstr ""

#: index.docbook:95
#, no-c-format
msgid "The time it takes the pling sound from the speakers to reach your ear."
msgstr ""

#: index.docbook:140
#, no-c-format
msgid ""
"The first three items are latencies external to &arts;. They are "
"interesting, but beyond the scope of this document. Nevertheless be aware "
"that they exist, so that even if you have optimized everything else to "
"really low values, you may not necessarily get exactly the result you "
"calculated."
msgstr ""

#: index.docbook:148
#, no-c-format
msgid ""
"Telling the server to play something involves usually one single &MCOP; "
"call. There are benchmarks which confirm that, on the same host with unix "
"domain sockets, telling the server to play something can be done about 9000 "
"times in one second with the current implementation. I expect that most of "
"this is kernel overhead, switching from one application to another. Of "
"course this value changes with the exact type of the parameters. If you "
"transfer a whole image with one call, it will be slower than if you transfer "
"only one long value. For the returncode the same is true. However for "
"ordinary strings (such as the filename of the <literal "
"role=\"extension\">wav</literal> file to play) this shouldn't be a problem."
msgstr ""

#: index.docbook:162
#, no-c-format
msgid ""
"That means, we can approximate this time with 1/9000 sec, that is below 0.15 "
"ms. We'll see that this is not relevant."
msgstr ""

#: index.docbook:167
#, no-c-format
msgid ""
"Next is the time between the server starting playing and the soundcard "
"getting something. The server needs to do buffering, so that when other "
"applications are running, such as your X11 server or "
"<quote>mousepling</quote>"
" application no dropouts are heard. The way this is done under &Linux; is "
"that there are a number fragments of a size. The server will refill "
"fragments, and the soundcard will play fragments."
msgstr ""

#: index.docbook:177
#, no-c-format
msgid ""
"So suppose there are three fragments. The server refills the first, the "
"soundcard starts playing it. The server refills the second. The server "
"refills the third. The server is done, other applications can do something "
"now."
msgstr ""

#: index.docbook:184
#, no-c-format
msgid ""
"As the soundcard has played the first fragment, it starts playing the second "
"and the server starts refilling the first. And so on."
msgstr ""

#: index.docbook:189
#, no-c-format
msgid ""
"The maximum latency you get with all that is (number of fragments)*(size of "
"each fragment)/(samplingrate * (size of each sample)). Suppose we assume "
"44kHz stereo, and 7 fragments a 1024 bytes (the current aRts defaults), we "
"get 40 ms."
msgstr ""

#: index.docbook:196
#, no-c-format
msgid ""
"These values can be tuned according to your needs. However, the "
"<acronym>CPU</acronym> usage increases with smaller latencies, as the sound "
"server needs to refill the buffers more often, and in smaller parts. It is "
"also mostly impossible to reach better values without giving the soundserver "
"realtime priority, as otherwise you'll often get drop-outs."
msgstr ""

#: index.docbook:205
#, no-c-format
msgid ""
"However, it is realistic to do something like 3 fragments with 256 bytes "
"each, which would make this value 4.4 ms. With 4.4ms delay the idle "
"<acronym>CPU</acronym>"
" usage of &arts; would be about 7.5%. With 40ms delay, it would be about 3% "
"(of a PII-350, and this value may depend on your soundcard, kernel version "
"and others)."
msgstr ""

#: index.docbook:213
#, no-c-format
msgid ""
"Then there is the time it takes the pling sound to get from the speakers to "
"your ear. Suppose your distance from the speakers is 2 meters. Sound travels "
"at a speed of 330 meters per second. So we can approximate this time with 6 "
"ms."
msgstr ""

#: index.docbook:223
#, no-c-format
msgid "Latency in Streaming Applications"
msgstr ""

#: index.docbook:225
#, no-c-format
msgid ""
"Streaming applications are those that produce their sound themselves. Assume "
"a game, which outputs a constant stream of samples, and should now be "
"adapted to replay things via &arts;. To have an example: when I press a key, "
"the figure which I am playing jumps, and a boing sound is played."
msgstr ""

#: index.docbook:233
#, no-c-format
msgid ""
"First of all, you need to know how &arts; does streaming. Its very similar "
"to the I/O with the soundcard. The game sends some packets with samples to "
"the sound server. Lets say three packets. As soon as the sound server is "
"done with the first packet, it sends a confirmation back to the game that "
"this packet is done."
msgstr ""

#: index.docbook:241
#, no-c-format
msgid ""
"The game creates another packet of sound and sends it to the server. "
"Meanwhile the server starts consuming the second sound packet, and so on. "
"The latency here looks similar like in the simple case:"
msgstr ""

#: index.docbook:247
#, no-c-format
msgid "The time until the kernel has notified the X11 server that a key was pressed."
msgstr ""

#: index.docbook:247
#, no-c-format
msgid "The time until the X11 server has notified the game that a key was pressed."
msgstr ""

#: index.docbook:247
#, no-c-format
msgid "The time until the game has decided that this key is worth playing a boing."
msgstr ""

#: index.docbook:247
#, no-c-format
msgid ""
"The time until the packet of sound in which the game has started putting the "
"boing sound is reaching the sound server."
msgstr ""

#: index.docbook:247
#, no-c-format
msgid ""
"The time it takes for the boing (which the soundserver starts mixing to the "
"other output at once) to go through the buffered data, until it really "
"reaches the position where the soundcard plays."
msgstr ""

#: index.docbook:247
#, no-c-format
msgid "The time it takes the boing sound from the speakers to reach your ear."
msgstr ""

#: index.docbook:293
#, no-c-format
msgid "The external latencies, as above, are beyond the scope of this document."
msgstr ""

#: index.docbook:297
#, no-c-format
msgid ""
"Obviously, the streaming latency depends on the time it takes all packets "
"that are used for streaming to be played once. So it is (number of "
"packets)*(size of each packet)/(samplingrate * (size of each sample))"
msgstr ""

#: index.docbook:303
#, no-c-format
msgid ""
"As you see that is the same formula as applies for the fragments. However "
"for games, it makes no sense to do such small delays as above. I'd say a "
"realistic configuration for games would be 2048 bytes per packet, use 3 "
"packets. The resulting latency would be 35ms."
msgstr ""

#: index.docbook:310
#, no-c-format
msgid ""
"This is based on the following: assume that the game renders 25 frames per "
"second (for the display). It is probably safe to assume that you won't "
"notice a difference of sound output of one frame. Thus 1/25 second delay for "
"streaming is acceptable, which in turn means 40ms would be okay."
msgstr ""

#: index.docbook:318
#, no-c-format
msgid ""
"Most people will also not run their games with realtime priority, and the "
"danger of drop-outs in the sound is not to be neglected. Streaming with 3 "
"packets a 256 bytes is possible (I tried that) - but causes a lot of "
"<acronym>CPU</acronym> usage for streaming."
msgstr ""

#: index.docbook:325
#, no-c-format
msgid "For server side latencies, you can calculate these exactly as above."
msgstr ""

#: index.docbook:332
#, no-c-format
msgid "Some <acronym>CPU</acronym> usage considerations"
msgstr ""

#: index.docbook:334
#, no-c-format
msgid ""
"There are a lot of factors which influence _<acronym>CPU</acronym> usage in "
"a complex scenario, with some streaming applications and some others, some "
"plugins on the server etc. To name a few:"
msgstr ""

#: index.docbook:340
#, no-c-format
msgid "Raw <acronym>CPU</acronym> usage by the calculations necessary."
msgstr ""

#: index.docbook:340
#, no-c-format
msgid ""
"&arts; internal scheduling overhead - how &arts; decides when which module "
"should calculate what."
msgstr ""

#: index.docbook:340
#, no-c-format
msgid "Integer to float conversion overhead."
msgstr ""

#: index.docbook:340
#, no-c-format
msgid "&MCOP;0 protocol overhead."
msgstr ""

#: index.docbook:340
#, no-c-format
msgid "Kernel: process/context switching."
msgstr ""

#: index.docbook:340
#, no-c-format
msgid "Kernel: communication overhead"
msgstr ""

#: index.docbook:379
#, no-c-format
msgid ""
"For raw <acronym>CPU</acronym> usage for calculations, if you play two "
"streams, simultaneuosly you need to do additions. If you apply a filter, "
"some calculations are involved. To have a simplified example, adding two "
"streams involves maybe four <acronym>CPU</acronym>"
" cycles per addition, on a 350Mhz processor, this is 44100*2*4/350000000 = "
"0.1% <acronym>CPU</acronym> usage."
msgstr ""

#: index.docbook:388
#, no-c-format
msgid ""
"&arts; internal scheduling: &arts; needs to decide which plugin when "
"calculates what. This takes time. Take a profiler if you are interested in "
"that. Generally what can be said is: the less realtime you do (&ie;. the "
"larger blocks can be calculated at a time) the less scheduling overhead you "
"have. Above calculating blocks of 128 samples at a time (thus using fragment "
"sizes of 512 bytes) the scheduling overhead is probably not worth thinking "
"about it."
msgstr ""

#: index.docbook:398
#, no-c-format
msgid ""
"Integer to float conversion overhead: &arts; uses floats internally as data "
"format. These are easy to handle and on recent processors not slower than "
"integer operations. However, if there are clients which play data which is "
"not float (like a game that should do its sound output via &arts;), it needs "
"to be converted. The same applies if you want to replay the sounds on your "
"soundcard. The soundcard wants integers, so you need to convert."
msgstr ""

#: index.docbook:408
#, no-c-format
msgid ""
"Here are numbers for a Celeron, approx. ticks per sample, with -O2 +egcs "
"2.91.66 (taken by Eugene Smith <email>hamster@null.ru</email>). This is of "
"course highly processor dependant:"
msgstr ""

#: index.docbook:414
#, no-c-format
msgid ""
"convert_mono_8_float: 14\n"
"convert_stereo_i8_2float: 28\n"
"convert_mono_16le_float: 40\n"
"interpolate_mono_16le_float: 200\n"
"convert_stereo_i16le_2float: 80\n"
"convert_mono_float_16le: 80"
msgstr ""

#: index.docbook:423
#, no-c-format
msgid ""
"So that means 1% <acronym>CPU</acronym> usage for conversion and 5% for "
"interpolation on this 350 MHz processor."
msgstr ""

#: index.docbook:428
#, no-c-format
msgid ""
"&MCOP; protocol overheadL &MCOP; does, as a rule of thumb, 9000 invocations "
"per second. Much of this is not &MCOP;s fault, but relates to the two kernel "
"causes named below. However, this gives a base to do calculations what the "
"cost of streaming is."
msgstr ""

#: index.docbook:435
#, no-c-format
msgid ""
"Each data packet transferred through streaming can be considered one &MCOP; "
"invocation. Of course large packets are slower than 9000 packets/s, but its "
"about the idea."
msgstr ""

#: index.docbook:441
#, no-c-format
msgid ""
"Suppose you use packet sizes of 1024 bytes. Thus, to transfer a stream with "
"44kHz stereo, you need to transfer 44100*4/1024 = 172 packets per second. "
"Suppose you could with 100% cpu usage transfer 9000 packets, then you get "
"(172*100)/9000 = 2% <acronym>CPU</acronym> usage due to streaming with 1024 "
"byte packets."
msgstr ""

#: index.docbook:449
#, no-c-format
msgid ""
"That are approximations. However, they show, that you would be much better "
"off (if you can afford it for the latency), to use for instance packets of "
"4096 bytes. We can make a compact formula here, by calculating the packet "
"size which causes 100% <acronym>CPU</acronym> usage as 44100*4/9000 = 19.6 "
"samples, and thus getting the quick formula:"
msgstr ""

#: index.docbook:457
#, no-c-format
msgid "streaming <acronym>CPU</acronym> usage in percent = 1960/(your packet size)"
msgstr ""

#: index.docbook:461
#, no-c-format
msgid ""
"which gives us 0.5% <acronym>CPU</acronym> usage when streaming with 4096 "
"byte packets."
msgstr ""

#: index.docbook:465
#, no-c-format
msgid ""
"Kernel process/context switching: this is part of the &MCOP; protocol "
"overhead. Switching between two processes takes time. There is new memory "
"mapping, the caches are invalid, whatever else (if there is a kernel expert "
"reading this - let me know what exactly are the causes). This means: it "
"takes time."
msgstr ""

#: index.docbook:473
#, no-c-format
msgid ""
"I am not sure how many context switches &Linux; can do per second, but that "
"number isn't infinite. Thus, of the &MCOP; protocol overhead I suppose quite "
"a bit is due to context switching. In the beginning of &MCOP;, I did tests "
"to use the same communication inside one process, and it was much faster "
"(four times as fast or so)."
msgstr ""

#: index.docbook:481
#, no-c-format
msgid ""
"Kernel: communication overhead: This is part of the &MCOP; protocol "
"overhead. Transferring data between processes is currently done via sockets. "
"This is convenient, as the usual select() methods can be used to determine "
"when a message has arrived. It can also be combined with other I/O sources "
"as audio I/O, X11 server or whatever else easily."
msgstr ""

#: index.docbook:489
#, no-c-format
msgid ""
"However, those read and write calls cost certainly processor cycles. For "
"small invocations (such as transferring one midi event) this is probably not "
"so bad, for large invocations (such as transferring one video frame with "
"several megabytes) this is clearly a problem."
msgstr ""

#: index.docbook:496
#, no-c-format
msgid ""
"Adding the usage of shared memory to &MCOP; where appropriate is probably "
"the best solution. However it should be done transparent to the application "
"programmer."
msgstr ""

#: index.docbook:502
#, no-c-format
msgid ""
"Take a profiler or do other tests to find out how much exactly current audio "
"streaming is impacted by the not using sharedmem. However, its not bad, as "
"audio streaming (replaying mp3) can be done with 6% total "
"<acronym>CPU</acronym> usage for &artsd; and "
"<application>artscat</application> (and 5% for the mp3 decoder). However, "
"this includes all things from the necessary calculations up do the socket "
"overhead, thus I'd say in this setup you could perhaps save 1% by using "
"sharedmem."
msgstr ""

#: index.docbook:516
#, no-c-format
msgid "Some Hard Numbers"
msgstr ""

#: index.docbook:518
#, no-c-format
msgid ""
"These are done with the current development snapshot. I also wanted to try "
"out the real hard cases, so this is not what everyday applications should "
"use."
msgstr ""

#: index.docbook:524
#, no-c-format
msgid ""
"I wrote an application called streamsound which sends streaming data to "
"&arts;. Here it is running with realtime priority (without problems), and "
"one small serverside (volume-scaling and clipping) plugin:"
msgstr ""

#: index.docbook:530
#, no-c-format
msgid ""
"4974 stefan    20   0  2360 2360  1784 S       0 17.7  1.8   0:21 artsd\n"
" 5016 stefan    20   0  2208 2208  1684 S       0  7.2  1.7   0:02 "
"streamsound\n"
" 5002 stefan    20   0  2208 2208  1684 S       0  6.8  1.7   0:07 "
"streamsound\n"
" 4997 stefan    20   0  2208 2208  1684 S       0  6.6  1.7   0:07 "
"streamsound"
msgstr ""

#: index.docbook:537
#, no-c-format
msgid ""
"Each of them is streaming with 3 fragments a 1024 bytes (18 ms). There are "
"three such clients running simultaneously. I know that that does look a bit "
"too much, but as I said: take a profiler and find out what costs time, and "
"if you like, improve it."
msgstr ""

#: index.docbook:544
#, no-c-format
msgid ""
"However, I don't think using streaming like that is realistic or makes "
"sense. To take it even more to the extreme, I tried what would be the lowest "
"latency possible. Result: you can do streaming without interruptions with "
"one client application, if you take 2 fragments of 128 bytes between aRts "
"and the soundcard, and between the client application and aRts. This means "
"that you have a total maximum latency of 128*4/44100*4 = 3 ms, where 1.5 ms "
"is generated due to soundcard I/O and 1.5 ms is generated through "
"communication with &arts;. Both applications need to run realtimed."
msgstr ""

#: index.docbook:556
#, no-c-format
msgid ""
"But: this costs an enormous amount of <acronym>CPU</acronym>. This example "
"cost you about 45% of my P-II/350. I also starts to click if you start top, "
"move windows on your X11 display or do disk I/O. All these are kernel "
"issues. The problem is that scheduling two or more applications with "
"realtime priority cost you an enormous amount of effort, too, even more if "
"the communicate, notify each other &etc;."
msgstr ""

#: index.docbook:566
#, no-c-format
msgid ""
"Finally, a more real life example. This is &arts; with artsd and one artscat "
"(one streaming client) running 16 fragments a 4096 bytes:"
msgstr ""

#: index.docbook:571
#, no-c-format
msgid ""
"5548 stefan    12   0  2364 2364  1752 R       0  4.9  1.8   0:03 artsd\n"
" 5554 stefan     3   0   752  752   572 R       0  0.7  0.5   0:00 top\n"
" 5550 stefan     2   0  2280 2280  1696 S       0  0.5  1.7   0:00 artscat"
msgstr ""

#: index.docbook:591
#, no-c-format
msgid "Busses"
msgstr ""

#: index.docbook:593
#, no-c-format
msgid ""
"Busses are dynamically built connections that transfer audio. Basically, "
"there are some uplinks and some downlinks. All signals from the uplinks are "
"added and send to the downlinks."
msgstr ""

#: index.docbook:599
#, no-c-format
msgid ""
"Busses as currently implemented operate in stereo, so you can only transfer "
"stereo data over busses. If you want mono data, well, transfer it only over "
"one channel and set the other to zero or whatever. What you need to to, is "
"to create one or more Synth&lowbar;BUS&lowbar;UPLINK objects and tell them a "
"bus name, to which they should talk (&eg; <quote>audio</quote> or "
"<quote>drums</quote>). Simply throw the data in there."
msgstr ""

#: index.docbook:609
#, no-c-format
msgid ""
"Then, you'll need to create one or more Synth&lowbar;BUS&lowbar;DOWNLINK "
"objects, and tell them the bus name (<quote>audio</quote> or "
"<quote>drums</quote> ... if it matches, the data will get through), and the "
"mixed data will come out again."
msgstr ""

#: index.docbook:616
#, no-c-format
msgid ""
"The uplinks and downlinks can reside in different structures, you can even "
"have different &artsbuilder;s running and start an uplink in one and receive "
"the data from the other with a downlink."
msgstr ""

#: index.docbook:622
#, no-c-format
msgid ""
"What is nice about busses is, that they are fully dynamic. Clients can plug "
"in and out on the fly. There should be no clicking or noise as this happens."
msgstr ""

#: index.docbook:628
#, no-c-format
msgid ""
"Of course, you should not plug out a client playing a signal, since it will "
"probably not be a zero level when plugged out the bus, and then it will "
"click."
msgstr ""

#: index.docbook:657
#, no-c-format
msgid "Trader"
msgstr ""

#: index.docbook:659
#, no-c-format
msgid ""
"&arts;/&MCOP; heavily relies on splitting up things into small components. "
"This makes things very flexible, as you can extend the system easily by "
"adding new components, which implement new effects, fileformats, "
"oscillators, gui elements, ... As almost everything is a component, almost "
"everything can be extended easily, without changing existing sources. New "
"components can be simply loaded dynamically to enhance already existing "
"applications."
msgstr ""

#: index.docbook:669
#, no-c-format
msgid "However, to make this work, two things are required:"
msgstr ""

#: index.docbook:673
#, no-c-format
msgid ""
"Components must advertise themselves - they must describe what great things "
"they offer, so that applications will be able to use them."
msgstr ""

#: index.docbook:673
#, no-c-format
msgid ""
"Applications must actively look for components that they could use, instead "
"of using always the same thing for some task."
msgstr ""

#: index.docbook:691
#, no-c-format
msgid ""
"The combination of this: components which say <quote>here I am, I am cool, "
"use me</quote>"
", and applications (or if you like, other components) which go out and look "
"which component they could use to get a thing done, is called trading."
msgstr ""

#: index.docbook:698
#, no-c-format
msgid ""
"In &arts;, components describe themselves by specifying values that they "
"<quote>support</quote>"
" for properties. A typical property for a file-loading component could be "
"the extension of the files that it can process. Typical values could be "
"<literal role=\"extension\">wav</literal>, <literal "
"role=\"extension\">aiff</literal> or <literal "
"role=\"extension\">mp3</literal>."
msgstr ""

#: index.docbook:707
#, no-c-format
msgid ""
"In fact, every component may choose to offer many different values for one "
"property. So one single component could offer reading both, <literal "
"role=\"extension\">wav</literal> and <literal "
"role=\"extension\">aiff</literal> files, by specifying that it supports "
"these values for the property <quote>Extension</quote>."
msgstr ""

#: index.docbook:715
#, no-c-format
msgid ""
"To do so, a component has to place a <literal "
"role=\"extension\">.mcopclass</literal> file at an appropriate place, "
"containing the properties it supports, for our example, this could look like "
"this (and would be installed in "
"<filename><replaceable>componentdir</replaceable>"
"/Arts/WavPlayObject.mcopclass</filename>):"
msgstr ""

#: index.docbook:723
#, no-c-format
msgid ""
"Interface=Arts::WavPlayObject,Arts::PlayObject,Arts::SynthModule,Arts::Object"
"\n"
"Author=\"Stefan Westerfeld &lt;stefan@space.twc.de&gt;\"\n"
"URL=\"http://www.arts-project.org\"\n"
"Extension=wav,aiff\n"
"MimeType=audio/x-wav,audio/x-aiff"
msgstr ""

#: index.docbook:731
#, no-c-format
msgid ""
"It is important that the filename of the <literal "
"role=\"extension\">.mcopclass</literal>"
"-file also says what the interface of the component is called like. The "
"trader doesn't look at the contents at all, if the file (like here) is "
"called <filename>Arts/WavPlayObject.mcopclass</filename>, the component "
"interface is called <interfacename>Arts::WavPlayObject</interfacename> "
"(modules map to directories)."
msgstr ""

#: index.docbook:741
#, no-c-format
msgid ""
"To look for components, there are two interfaces (which are defined in "
"<filename>core.idl</filename>, so you have them in every application), "
"called <interfacename>Arts::TraderQuery</interfacename> and "
"<interfacename>Arts::TraderOffer</interfacename>. You to go on a "
"<quote>shopping tour</quote> for components like this:"
msgstr ""

#: index.docbook:749
#, no-c-format
msgid "Create a query object:"
msgstr ""

#: index.docbook:749
#, no-c-format
msgid "Arts::TraderQuery query;"
msgstr ""

#: index.docbook:749
#, no-c-format
msgid ""
"Specify what you want. As you saw above, components describe themselves "
"using properties, for which they offer certain values. So specifying what "
"you want is done by selecting components that support a certain value for a "
"property. This is done using the supports method of a TraderQuery:"
msgstr ""

#: index.docbook:749
#, no-c-format
msgid ""
"query.supports(\"Interface\",\"Arts::PlayObject\");\n"
"    query.supports(\"Extension\",\"wav\");"
msgstr ""

#: index.docbook:749
#, no-c-format
msgid ""
"Finally, perform the query using the query method. Then, you'll (hopefully) "
"get some offers:"
msgstr ""

#: index.docbook:749
#, no-c-format
msgid "vector&lt;Arts::TraderOffer&gt; *offers = query.query();"
msgstr ""

#: index.docbook:749
#, no-c-format
msgid ""
"Now you can examine what you found. Important is the interfaceName method of "
"TraderOffer, which will tell you the name of the component, that matched the "
"query. You can also find out further properties by getProperty. The "
"following code will simply iterate through all components, print their "
"interface names (which could be used for creation), and delete the results "
"of the query again:"
msgstr ""

#: index.docbook:749
#, no-c-format
msgid ""
"vector&lt;Arts::TraderOffer&gt;::iterator i;\n"
"    for(i = offers-&gt;begin(); i != offers-&gt;end(); i++)\n"
"        cout &lt;&lt; i-&gt;interfaceName() &lt;&lt; endl;\n"
"    delete offers;"
msgstr ""

#: index.docbook:803
#, no-c-format
msgid ""
"For this kind of trading service to be useful, it is important to somehow "
"agree on what kinds of properties components should usually define. It is "
"essential that more or less all components in a certain area use the same "
"set of properties to describe themselves (and the same set of values where "
"applicable), so that applications (or other components) will be able to find "
"them."
msgstr ""

#: index.docbook:812
#, no-c-format
msgid ""
"Author (type string, optional): This can be used to ultimately let the world "
"know that you wrote something. You can write anything you like in here, "
"e-mail adress is of course helpful."
msgstr ""

#: index.docbook:818
#, no-c-format
msgid ""
"Buildable (type boolean, recommended): This indicates whether the component "
"is usable with <acronym>RAD</acronym> tools (such as &artsbuilder;) which "
"use components by assigning properties and connecting ports. It is "
"recommended to set this value to true for almost any signal processing "
"component (such as filters, effects, oscillators, ...), and for all other "
"things which can be used in <acronym>RAD</acronym>"
" like fashion, but not for internal stuff like for instance "
"<interfacename>Arts::InterfaceRepo</interfacename>."
msgstr ""

#: index.docbook:829
#, no-c-format
msgid ""
"Extension (type string, used where relevant): Everything dealing with files "
"should consider using this. You should put the lowercase version of the file "
"extension without the <quote>.</quote> here, so something like "
"<userinput>wav</userinput> should be fine."
msgstr ""

#: index.docbook:836
#, no-c-format
msgid ""
"Interface (type string, required): This should include the full list of "
"(useful) interfaces your components supports, probably including "
"<interfacename>Arts::Object</interfacename> and if applicable "
"<interfacename>Arts::SynthModule</interfacename>."
msgstr ""

#: index.docbook:843
#, no-c-format
msgid ""
"Language (type string, recommended): If you want your component to be "
"dynamically loaded, you need to specify the language here. Currently, the "
"only allowed value is <userinput>C++</userinput>, which means the component "
"was written using the normal C++ <acronym>API</acronym>. If you do so, "
"you'll also need to set the <quote>Library</quote> property below."
msgstr ""

#: index.docbook:852
#, no-c-format
msgid ""
"Library (type string, used where relevant): Components written in C++ can be "
"dynamically loaded. To do so, you have to compile them into a dynamically "
"loadable libtool (<literal role=\"extension\">.la</literal>) module. Here, "
"you can specify the name of the <literal "
"role=\"extension\">.la</literal>"
"-File that contains your component. Remember to use REGISTER_IMPLEMENTATION "
"(as always)."
msgstr ""

#: index.docbook:861
#, no-c-format
msgid ""
"MimeType (type string, used where relevant): Everything dealing with files "
"should consider using this. You should put the lowercase version of the "
"standard mimetype here, for instance <userinput>audio/x-wav</userinput>."
msgstr ""

#: index.docbook:868
#, no-c-format
msgid ""
"&URL; (type string, optional): If you like to let people know where they can "
"find a new version of the component (or a homepage or anything), you can do "
"it here. This should be standard &HTTP; or &FTP; &URL;."
msgstr ""

#: index.docbook:903
#, no-c-format
msgid "Namespaces in &arts;"
msgstr ""

#: index.docbook:906
#, no-c-format
msgid "Introduction"
msgstr "Ukwazisa"

#: index.docbook:908
#, no-c-format
msgid ""
"Each namespace declaration corresponds to a <quote>module</quote> "
"declaration in the &MCOP; &IDL;."
msgstr ""

#: index.docbook:913
#, no-c-format
msgid ""
"// mcop idl\n"
"\n"
"module M {\n"
"    interface A\n"
"    {\n"
"    }\n"
"};\n"
"\n"
"interface B;"
msgstr ""

#: index.docbook:925
#, no-c-format
msgid ""
"In this case, the generated C++ code for the &IDL; snippet would look like "
"this:"
msgstr ""

#: index.docbook:930
#, no-c-format
msgid ""
"// C++ header\n"
"\n"
"namespace M {\n"
"    /* declaration of A_base/A_skel/A_stub and similar */\n"
"    class A {        // Smartwrapped reference class\n"
"        /* [...] */\n"
"    };\n"
"}\n"
"\n"
"/* declaration of B_base/B_skel/B_stub and similar */\n"
"class B {\n"
"    /* [...] */\n"
"};"
msgstr ""

#: index.docbook:946
#, no-c-format
msgid ""
"So when referring the classes from the above example in your C++ code, you "
"would have to write <classname>M::A</classname>, but only B. However, you "
"can of course use <quote>using M</quote>"
" somewhere - like with any namespace in C++."
msgstr ""

#: index.docbook:956
#, no-c-format
msgid "How &arts; uses namespaces"
msgstr ""

#: index.docbook:958
#, no-c-format
msgid ""
"There is one global namespace called <quote>Arts</quote>"
", which all programs and libraries that belong to &arts; itself use to put "
"their declarations in. This means, that when writing C++ code that depends "
"on &arts;, you normally have to prefix every class you use with "
"<classname>Arts::</classname>, like this:"
msgstr ""

#: index.docbook:966
#, no-c-format
msgid ""
"int main(int argc, char **argv)\n"
"{\n"
"    Arts::Dispatcher dispatcher;\n"
"    Arts::SimpleSoundServer "
"server(Arts::Reference(\"global:Arts_SimpleSoundServer\"));\n"
"\n"
"    server.play(\"/var/foo/somefile.wav\");"
msgstr ""

#: index.docbook:975
#, no-c-format
msgid "The other alternative is to write a using once, like this:"
msgstr ""

#: index.docbook:979
#, no-c-format
msgid ""
"using namespace Arts;\n"
"\n"
"int main(int argc, char **argv)\n"
"{\n"
"    Dispatcher dispatcher;\n"
"    SimpleSoundServer server(Reference(\"global:Arts_SimpleSoundServer\"));\n"
"\n"
"    server.play(\"/var/foo/somefile.wav\");\n"
"    [...]"
msgstr ""

#: index.docbook:991
#, no-c-format
msgid ""
"In &IDL; files, you don't exactly have a choice. If you are writing code "
"that belongs to &arts; itself, you'll have to put it into module &arts;."
msgstr ""

#: index.docbook:996
#, no-c-format
msgid ""
"// IDL File for aRts code:\n"
"#include &lt;artsflow.idl&gt;\n"
"module Arts {        // put it into the Arts namespace\n"
"    interface Synth_TWEAK : SynthModule\n"
"    {\n"
"        in audio stream invalue;\n"
"        out audio stream outvalue;\n"
"        attribute float tweakFactor;\n"
"    };\n"
"};"
msgstr ""

#: index.docbook:1009
#, no-c-format
msgid ""
"If you write code that doesn't belong to &arts; itself, you should not put "
"it into the <quote>Arts</quote> namespace. However, you can make an own "
"namespace if you like. In any case, you'll have to prefix classes you use "
"from &arts;."
msgstr ""

#: index.docbook:1016
#, no-c-format
msgid ""
"// IDL File for code which doesn't belong to aRts:\n"
"#include &lt;artsflow.idl&gt;\n"
"\n"
"// either write without module declaration, then the generated classes will\n"
"// not use a namespace:\n"
"interface Synth_TWEAK2 : Arts::SynthModule\n"
"{\n"
"    in audio stream invalue;\n"
"    out audio stream outvalue;\n"
"    attribute float tweakFactor;\n"
"};\n"
"\n"
"// however, you can also choose your own namespace, if you like, so if you\n"
"// write an application \"PowerRadio\", you could for instance do it like "
"this:\n"
"module PowerRadio {\n"
"    struct Station {\n"
"        string name;\n"
"        float frequency;\n"
"    };\n"
"\n"
"    interface Tuner : Arts::SynthModule {\n"
"        attribute Station station;     // no need to prefix Station, same "
"module\n"
"        out audio stream left, right;\n"
"    };\n"
"};"
msgstr ""

#: index.docbook:1047
#, no-c-format
msgid "Internals: How the Implementation Works"
msgstr ""

#: index.docbook:1049
#, no-c-format
msgid ""
"Often, in interfaces, casts, method signatures and similar, &MCOP; needs to "
"refer to names of types or interfaces. These are represented as string in "
"the common &MCOP; datastructures, while the namespace is always fully "
"represented in the C++ style. This means the strings would contain "
"<quote>M::A</quote> and <quote>B</quote>, following the example above."
msgstr ""

#: index.docbook:1058
#, no-c-format
msgid ""
"Note this even applies if inside the &IDL; text the namespace qualifiers "
"were not given, since the context made clear which namespace the interface "
"<interfacename>A</interfacename> was meant to be used in."
msgstr ""

#: index.docbook:1068
#, no-c-format
msgid "Threads in &arts;"
msgstr ""

#: index.docbook:1071
#, no-c-format
msgid "Basics"
msgstr ""

#: index.docbook:1073
#, no-c-format
msgid ""
"Using threads isn't possible on all platforms. This is why &arts; was "
"originally written without using threading at all. For almost all problems, "
"for each threaded solution to the problem, there is a non-threaded solution "
"that does the same."
msgstr ""

#: index.docbook:1080
#, no-c-format
msgid ""
"For instance, instead of putting audio output in a seperate thread, and make "
"it blocking, &arts; uses non-blocking audio output, and figures out when to "
"write the next chunk of data using <function>select()</function>."
msgstr ""

#: index.docbook:1087
#, no-c-format
msgid ""
"However, &arts; (in very recent versions) at least provides support for "
"people who do want to implement their objects using threads. For instance, "
"if you already have code for an <literal role=\"extension\">mp3</literal> "
"player, and the code expects the <literal role=\"extension\">mp3</literal> "
"decoder to run in a seperate thread, it's usally the easiest thing to do to "
"keep this design."
msgstr ""

#: index.docbook:1096
#, no-c-format
msgid ""
"The &arts;/&MCOP; implementation is built along sharing state between "
"seperate objects in obvious and non-obvious ways. A small list of shared "
"state includes:"
msgstr ""

#: index.docbook:1102
#, no-c-format
msgid "The Dispatcher object which does &MCOP; communication."
msgstr ""

#: index.docbook:1102
#, no-c-format
msgid "The Reference counting (Smartwrappers)."
msgstr ""

#: index.docbook:1102
#, no-c-format
msgid "The IOManager which does timer and fd watches."
msgstr ""

#: index.docbook:1102
#, no-c-format
msgid "The ObjectManager which creates objects and dynamically loads plugins."
msgstr ""

#: index.docbook:1102
#, no-c-format
msgid "The FlowSystem which calls calculateBlock in the appropriate situations."
msgstr ""

#: index.docbook:1133
#, no-c-format
msgid ""
"All of the above objects don't expect to be used concurrently (&ie; called "
"from seperate threads at the same time). Generally there are two ways of "
"solving this:"
msgstr ""

#: index.docbook:1139
#, no-c-format
msgid ""
"Require the caller of any functions on this objects to acquire a lock before "
"using them."
msgstr ""

#: index.docbook:1139
#, no-c-format
msgid ""
"Making these objects really threadsafe and/or create per-thread instances of "
"them."
msgstr ""

#: index.docbook:1155
#, no-c-format
msgid ""
"&arts; follows the first approach: you will need a lock whenever you talk to "
"any of these objects. The second approach is harder to do. A hack which "
"tries to achieve this is available at <ulink "
"url=\"http://space.twc.de/~stefan/kde/download/arts-mt.tar.gz\"> "
"http://space.twc.de/~stefan/kde/download/arts-mt.tar.gz</ulink>"
", but for the current point in time, a minimalistic approach will probably "
"work better, and cause less problems with existing applications."
msgstr ""

#: index.docbook:1167
#, no-c-format
msgid "When/how to acquire the lock?"
msgstr ""

#: index.docbook:1169
#, no-c-format
msgid "You can get/release the lock with the two functions:"
msgstr ""

#: index.docbook:1173
#, no-c-format
msgid "Arts::Dispatcher::lock()"
msgstr ""

#: index.docbook:1173
#, no-c-format
msgid "Arts::Dispatcher::unlock()"
msgstr ""

#: index.docbook:1188
#, no-c-format
msgid ""
"Generally, you don't need to acquire the lock (and you shouldn't try to do "
"so), if it is already held. A list of conditions when this is the case is:"
msgstr ""

#: index.docbook:1194
#, no-c-format
msgid "You receive a callback from the IOManager (timer or fd)."
msgstr ""

#: index.docbook:1194
#, no-c-format
msgid "You get call due to some &MCOP; request."
msgstr ""

#: index.docbook:1194
#, no-c-format
msgid "You are called from the NotificationManager."
msgstr ""

#: index.docbook:1194
#, no-c-format
msgid "You are called from the FlowSystem (calculateBlock)"
msgstr ""

#: index.docbook:1220
#, no-c-format
msgid ""
"There are also some exceptions of functions. which you can only call in the "
"main thread, and for that reason you will never need a lock to call them:"
msgstr ""

#: index.docbook:1226
#, no-c-format
msgid "Constructor/destructor of Dispatcher/IOManager."
msgstr ""

#: index.docbook:1226
#, no-c-format
msgid ""
"<methodname>Dispatcher::run()</methodname> / "
"<methodname>IOManager::run()</methodname>"
msgstr ""

#: index.docbook:1226
#, no-c-format
msgid "IOManager::processOneEvent()"
msgstr ""

#: index.docbook:1245
#, no-c-format
msgid ""
"But that is it. For everything else that is somehow related to &arts;, you "
"will need to get the lock, and release it again when done. Always. Here is a "
"simple example:"
msgstr ""

#: index.docbook:1251
#, no-c-format
msgid ""
"class SuspendTimeThread : Arts::Thread {\n"
"public:\n"
"    void run() {\n"
"        /*\n"
"         * you need this lock because:\n"
"         *  - constructing a reference needs a lock (as global: will go to\n"
"         *    the object manager, which might in turn need the GlobalComm\n"
"         *    object to look up where to connect to)\n"
"         *  - assigning a smartwrapper needs a lock\n"
"         *  - constructing an object from reference needs a lock (because "
"it\n"
"         *    might need to connect a server)\n"
"         */\n"
"        Arts::Dispatcher::lock();\n"
"        Arts::SoundServer server = "
"Arts::Reference(\"global:Arts_SoundServer\");\n"
"        Arts::Dispatcher::unlock();\n"
"\n"
"        for(;;) {            /*\n"
"             * you need a lock here, because\n"
"             *  - dereferencing a smartwrapper needs a lock (because it "
"might\n"
"             *    do lazy creation)\n"
"             *  - doing an MCOP invocation needs a lock\n"
"             */\n"
"            Arts::Dispatcher::lock();\n"
"            long seconds = server.secondsUntilSuspend();\n"
"            Arts::Dispatcher::unlock();\n"
"\n"
"            printf(\"seconds until suspend = %d\",seconds);\n"
"            sleep(1);\n"
"        }\n"
"    }\n"
"}"
msgstr ""

#: index.docbook:1289
#, no-c-format
msgid "Threading related classes"
msgstr ""

#: index.docbook:1291
#, no-c-format
msgid "The following threading related classes are currently available:"
msgstr ""

#: index.docbook:1295
#, no-c-format
msgid ""
"<ulink "
"url=\"http://www.arts-project.org/doc/headers/Arts__Thread.html\"><classname>"
" Arts::Thread</classname></ulink> - which encapsulates a thread."
msgstr ""

#: index.docbook:1295
#, no-c-format
msgid ""
"<ulink url=\"http://www.arts-project.org/doc/headers/Arts__Mutex.html\"> "
"<classname>Arts::Mutex</classname></ulink> - which encapsulates a mutex."
msgstr ""

#: index.docbook:1295
#, no-c-format
msgid ""
"<ulink "
"url=\"http://www.arts-project.org/doc/headers/Arts__ThreadCondition.html\"> "
"<classname>Arts::ThreadCondition</classname></ulink> - which provides "
"support to wake up threads which are waiting for a certain condition to "
"become true."
msgstr ""

#: index.docbook:1295
#, no-c-format
msgid ""
"<ulink "
"url=\"http://www.arts-project.org/doc/headers/Arts__SystemThreads.html\">"
"<classname>Arts::SystemThreads</classname></ulink> - which encapsulates the "
"operating system threading layer (which offers a few helpful functions to "
"application programmers)."
msgstr ""

#: index.docbook:1331
#, no-c-format
msgid "See the links for documentation."
msgstr ""

#: index.docbook:1339
#, no-c-format
msgid "References and Error Handling"
msgstr ""

#: index.docbook:1341
#, no-c-format
msgid ""
"&MCOP; references are one of the most central concepts in &MCOP; "
"programming. This section will try to describe how exactly references are "
"used, and will especially also try to cover cases of failure (server "
"crashes)."
msgstr ""

#: index.docbook:1349
#, no-c-format
msgid "Basic properties of references"
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid ""
"An &MCOP; reference is not an object, but a reference to an object: Even "
"though the following declaration <programlisting>\n"
"   Arts::Synth_PLAY p;\n"
"</programlisting> looks like a definition of an object, it only declares a "
"reference to an object. As C++ programmer, you might also think of it as "
"Synth_PLAY *, a kind of pointer to a Synth_PLAY object. This especially "
"means, that p can be the same thing as a NULL pointer."
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid "You can create a NULL reference by assigning it explicitly"
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid "Arts::Synth_PLAY p = Arts::Synth_PLAY::null();"
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid "Invoking things on a NULL reference leads to a core dump"
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid ""
"Arts::Synth_PLAY p = Arts::Synth_PLAY::null();\n"
"   string s = p.toString();"
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid ""
"will lead to a core dump. Comparing this to a pointer, it is essentially the "
"same as <programlisting>\n"
"   QWindow* w = 0;\n"
"   w-&gt;show();\n"
"</programlisting> which every C++ programmer would know to avoid."
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid "Uninitialized objects try to lazy-create themselves upon first use"
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid ""
"Arts::Synth_PLAY p;\n"
"   string s = p.toString();"
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid ""
"is something different than dereferencing a NULL pointer. You didn't tell "
"the object at all what it is, and now you try to use it. The guess here is "
"that you want to have a new local instance of a Arts::Synth_PLAY object. Of "
"course you might have wanted something else (like creating the object "
"somewhere else, or using an existing remote object). However, it is a "
"convenient short cut to creating objects. Lazy creation will not work once "
"you assigned something else (like a null reference)."
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid ""
"The equivalent C++ terms would be <programlisting>\n"
"   QWidget* w;\n"
"   w-&gt;show();\n"
"</programlisting> which obviously in C++ just plain segfaults. So this is "
"different here. This lazy creation is tricky especially as not necessarily "
"an implementation exists for your interface."
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid ""
"For instance, consider an abstract thing like a Arts::PlayObject. There are "
"certainly concrete PlayObjects like those for playing mp3s or wavs, but "
"<programlisting>\n"
"   Arts::PlayObject po;\n"
"   po.play();\n"
"</programlisting> will certainly fail. The problem is that although lazy "
"creation kicks in, and tries to create a PlayObject, it fails, because there "
"are only things like Arts::WavPlayObject and similar. Thus, use lazy "
"creation only when you are sure that an implementation exists."
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid "References may point to the same object"
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid ""
"Arts::SimpleSoundServer s = "
"Arts::Reference(\"global:Arts_SimpleSoundServer\");\n"
"   Arts::SimpleSoundServer s2 = s;"
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid ""
"creates two references referring to the same object. It doesn't copy any "
"value, and doesn't create two objects."
msgstr ""

#: index.docbook:1351
#, no-c-format
msgid ""
"All objects are reference counted So once an object isn't referred any "
"longer by any references, it gets deleted. There is no way to explicitely "
"delete an object, however, you can use something like this <programlisting>\n"
"   Arts::Synth_PLAY p;\n"
"   p.start();\n"
"   [...]\n"
"   p = Arts::Synth_PLAY::null();\n"
"</programlisting> to make the Synth_PLAY object go away in the end. "
"Especially, it should never be necessary to use new and delete in "
"conjunction with references."
msgstr ""

#: index.docbook:1480
#, no-c-format
msgid "The case of failure"
msgstr ""

#: index.docbook:1482
#, no-c-format
msgid ""
"As references can point to remote objects, the servers containing these "
"objects can crash. What happens then?"
msgstr ""

#: index.docbook:1487
#, no-c-format
msgid ""
"A crash doesn't change whether a reference is a null reference. This means "
"that if <function>foo.isNull()</function> was "
"<returnvalue>true</returnvalue> before a server crash then it is also "
"<returnvalue>true</returnvalue> after a server crash (which is clear). It "
"also means that if <function>foo.isNull()</function> was "
"<returnvalue>false</returnvalue> before a server crash (foo referred to an "
"object) then it is also <returnvalue>false</returnvalue> after the server "
"crash."
msgstr ""

#: index.docbook:1487
#, no-c-format
msgid ""
"Invoking methods on a valid reference stays safe Suppose the server "
"containing the object calc crashed. Still calling things like "
"<programlisting>\n"
"   int k = calc.subtract(i,j)\n"
"</programlisting>"
" are safe. Obviously subtract has to return something here, which it can't "
"because the remote object no longer exists. In this case (k == 0) would be "
"true. Generally, operations try to return something <quote>neutral</quote> "
"as result, such as 0.0, a null reference for objects or empty strings, when "
"the object no longer exists."
msgstr ""

#: index.docbook:1487
#, no-c-format
msgid "Checking <function>error()</function> reveals whether something worked."
msgstr ""

#: index.docbook:1487
#, no-c-format
msgid ""
"In the above case, <programlisting>\n"
"   int k = calc.subtract(i,j)\n"
"   if(k.error()) {\n"
"      printf(\"k is not i-j!\\n\");\n"
"   }\n"
"</programlisting> would print out <computeroutput>k is not "
"i-j</computeroutput> whenever the remote invocation didn't work. Otherwise "
"<varname>k</varname> is really the result of the subtract operation as "
"performed by the remote object (no server crash). However, for methods doing "
"things like deleting a file, you can't know for sure whether it really "
"happened. Of course it happened if <function>.error()</function> is "
"<returnvalue>false</returnvalue>. However, if <function>.error()</function> "
"is <returnvalue>true</returnvalue>, there are two possibilities:"
msgstr ""

#: index.docbook:1487
#, no-c-format
msgid ""
"The file got deleted, and the server crashed just after deleting it, but "
"before transferring the result."
msgstr ""

#: index.docbook:1487
#, no-c-format
msgid "The server crashed before beeing able to delete the file."
msgstr ""

#: index.docbook:1487
#, no-c-format
msgid "Using nested invocations is dangerous in crash resistent programs"
msgstr ""

#: index.docbook:1487
#, no-c-format
msgid ""
"Using something like <programlisting>\n"
"   window.titlebar().setTitle(\"foo\");\n"
"</programlisting> is not a good idea. Suppose you know that window contains "
"a valid Window reference. Suppose you know that "
"<function>window.titlebar()</function> will return a Titlebar reference "
"because the Window object is implemented properly. However, still the above "
"statement isn't safe."
msgstr ""

#: index.docbook:1487
#, no-c-format
msgid ""
"What could happen is that the server containing the Window object has "
"crashed. Then, regardless of how good the Window implementation is, you will "
"get a null reference as result of the window.titlebar() operation. And then "
"of course invoking setTitle on that null reference will lead to a crash as "
"well."
msgstr ""

#: index.docbook:1487
#, no-c-format
msgid ""
"So a safe variant of this would be <programlisting>\n"
"   Titlebar titlebar = window.titlebar();\n"
"   if(!window.error())\n"
"      titlebar.setTitle(\"foo\");\n"
"</programlisting> add the appropriate error handling if you like. If you "
"don't trust the Window implementation, you might as well use "
"<programlisting>\n"
"   Titlebar titlebar = window.titlebar();\n"
"   if(!titlebar.isNull())\n"
"      titlebar.setTitle(\"foo\");\n"
"</programlisting> which are both safe."
msgstr ""

#: index.docbook:1601
#, no-c-format
msgid ""
"There are other conditions of failure, such as network disconnection "
"(suppose you remove the cable between your server and client while your "
"application runs). However their effect is the same like a server crash."
msgstr ""

#: index.docbook:1607
#, no-c-format
msgid ""
"Overall, it is of course a consideration of policy how strictly you try to "
"trap communcation errors throughout your application. You might follow the "
"<quote>if the server crashes, we need to debug the server until it never "
"crashes again</quote>"
" method, which would mean you need not bother about all these problems."
msgstr ""

#: index.docbook:1618
#, no-c-format
msgid "Internals: Distributed Reference Counting"
msgstr ""

#: index.docbook:1620
#, no-c-format
msgid ""
"An object, to exist, must be owned by someone. If it isn't, it will cease to "
"exist (more or less) immediately. Internally, ownership is indicated by "
"calling <function>_copy()</function>, which increments an reference count, "
"and given back by calling <function>_release()</function>. As soon as the "
"reference count drops to zero, a delete will be done."
msgstr ""

#: index.docbook:1629
#, no-c-format
msgid ""
"As a variation of the theme, remote usage is indicated by "
"<function>_useRemote()</function>, and dissolved by "
"<function>_releaseRemote()</function>. These functions lead a list which "
"server has invoked them (and thus owns the object). This is used in case "
"this server disconnects (&ie; crash, network failure), to remove the "
"references that are still on the objects. This is done in "
"<function>_disconnectRemote()</function>."
msgstr ""

#: index.docbook:1639
#, no-c-format
msgid ""
"Now there is one problem. Consider a return value. Usually, the return value "
"object will not be owned by the calling function any longer. It will however "
"also not be owned by the caller, until the message holding the object is "
"received. So there is a time of <quote>ownershipless</quote> objects."
msgstr ""

#: index.docbook:1647
#, no-c-format
msgid ""
"Now, when sending an object, one can be reasonable sure that as soon as it "
"is received, it will be owned by somebody again, unless, again, the receiver "
"dies. However this means that special care needs to be taken about object at "
"least while sending, probably also while receiving, so that it doesn't die "
"at once."
msgstr ""

#: index.docbook:1655
#, no-c-format
msgid ""
"The way &MCOP; does this is by <quote>tagging</quote> objects that are in "
"process of being copied across the wire. Before such a copy is started, "
"<function>_copyRemote</function> is called. This prevents the object from "
"being freed for a while (5 seconds). Once the receiver calls "
"<function>_useRemote()</function>, the tag is removed again. So all objects "
"that are send over wire are tagged before transfer."
msgstr ""

#: index.docbook:1664
#, no-c-format
msgid ""
"If the receiver receives an object which is on his server, of course he will "
"not <function>_useRemote()</function> it. For this special case, "
"<function>_cancelCopyRemote()</function> exists to remove the tag manually. "
"Other than that, there is also timer based tag removal, if tagging was done, "
"but the receiver didn't really get the object (due to crash, network "
"failure). This is done by the <classname>ReferenceClean</classname> class."
msgstr ""

#: index.docbook:1679
#, no-c-format
msgid "&GUI; Elements"
msgstr ""

#: index.docbook:1681
#, no-c-format
msgid ""
"&GUI; elements are currently in the experimental state. However, this "
"section will describe what is supposed to happen here, so if you are a "
"developer, you will be able to understand how &arts; will deal with &GUI;s "
"in the future. There is some code there already, too."
msgstr ""

#: index.docbook:1688
#, no-c-format
msgid ""
"&GUI; elements should be used to allow synthesis structures to interact with "
"the user. In the simplest case, the user should be able to modify some "
"parameters of a structure directly (such as a gain factor which is used "
"before the final play module)."
msgstr ""

#: index.docbook:1695
#, no-c-format
msgid ""
"In more complex settings, one could imagine the user modifying parameters of "
"groups of structures and/or not yet running structures, such as modifying "
"the <acronym>ADSR</acronym> envelope of the currently active &MIDI; "
"instrument. Another thing would be setting the filename of some sample based "
"instrument."
msgstr ""

#: index.docbook:1703
#, no-c-format
msgid ""
"On the other hand, the user could like to monitor what the synthesizer is "
"doing. There could be oscilloscopes, spectrum analyzers, volume meters and "
"<quote>experiments</quote> that figure out the frequency transfer curve of "
"some given filter module."
msgstr ""

#: index.docbook:1710
#, no-c-format
msgid ""
"Finally, the &GUI; elements should be able to control the whole structure of "
"what is running inside &arts; and how. The user should be able to assign "
"instruments to midi channels, start new effect processors, configure his "
"main mixer pult (which is built of &arts; structures itself) to have one "
"channel more and use another strategy for its equalizers."
msgstr ""

#: index.docbook:1719
#, no-c-format
msgid ""
"You see - the <acronym>GUI</acronym>"
" elements should bring all possibilities of the virtual studio &arts; should "
"simulate to the user. Of course, they should also gracefully interact with "
"midi inputs (such as sliders should move if they get &MIDI; inputs which "
"also change just that parameter), and probably even generate events "
"themselves, to allow the user interaction to be recorded via sequencer."
msgstr ""

#: index.docbook:1728
#, no-c-format
msgid ""
"Technically, the idea is to have an &IDL; base class for all widgets "
"(<classname>Arts::Widget</classname>), and derive a number of commonly used "
"widgets from there (like <classname>Arts::Poti</classname>, "
"<classname>Arts::Panel</classname>, <classname>Arts::Window</classname>, "
"...)."
msgstr ""

#: index.docbook:1736
#, no-c-format
msgid ""
"Then, one can implement these widgets using a toolkit, for instance &Qt; or "
"Gtk. Finally, effects should build their &GUI;s out of existing widgets. For "
"instance, a freeverb effect could build it's &GUI; out of five "
"<classname>Arts::Poti</classname> thingies and an "
"<classname>Arts::Window</classname>. So IF there is a &Qt; implementation "
"for these base widgets, the effect will be able to display itself using "
"&Qt;. If there is Gtk implementation, it will also work for Gtk (and more or "
"less look/work the same)."
msgstr ""

#: index.docbook:1747
#, no-c-format
msgid ""
"Finally, as we're using &IDL; here, &artsbuilder; (or other tools) will be "
"able to plug &GUI;s together visually, or autogenerate &GUI;s given hints "
"for parameters, only based on the interfaces. It should be relatively "
"straight forward to write a <quote>create &GUI; from description</quote> "
"class, which takes a &GUI; description (containing the various parameters "
"and widgets), and creates a living &GUI; object out of it."
msgstr ""

#: index.docbook:1757
#, no-c-format
msgid ""
"Based on &IDL; and the &arts;/&MCOP; component model, it should be easy to "
"extend the possible objects which can be used for the &GUI; just as easy as "
"it is to add a plugin implementing a new filter to &arts;."
msgstr ""
