Swoole-src: Improve English documentation

[moon0326]

Please answer these questions before submitting your issue. Thanks!

1. What did you do? If possible, provide a recipe for reproducing the error.

   read Chinese and English documentation

2. What did you expect to see?

I expected to find best practice for production usage

1. What did you see instead?

nothing

1. What version of Swoole are you using (php --ri swoole)?

latest.

1. What is your machine environment used (including version of kernel & php & gcc) ?

ubuntu

1. If you are using ssl, what is your openssl version?

latest

Hi,

I have a new product that is using Guzzle heavily. I would like to switch to swoole. I noticed that my worker exit time to time, but I wasn't sure if they get restarted or not.

Are there any documentations or blog posts that I can refer how I can recover or watch workers?

And...please invite people to slack..me and other people have submitted the form, but still have no invitation yet.

Thanks!

[twose]

don't use exit in swoole server, and the worker will automatic restart

[ghost]

This project is very powerful, and a documentation hard to maintain - but, working together and contribute could help. Maybe, an issue as overall overview about documention needs and questions could be helpful to organize this and to let users explain their needs @ swoole team :)

[ghost]

BTW: i would like to have a github book for swoole, like this one https://crystal-lang.org/docs/overview/

So, if @twose or swoole team would like to maintain, we could talk about it and the content and can provide first class docs in future :) As far as it is public, its free with gitbook :) And they have already a good tooling about viewings etc. You simply add all pages online, markdown, very easy :+1:

[moon0326]

@flddr I don't understand what part you want me to delete. Could you be more specific please?

[moon0326]

@flddr sure, I've deleted them :)

[twose]

in fact, I try to google translate but I still can hardly understand something you said...
to do my best, I try to explain these:
we have a plan to create a repository in Github and use markdown to write documentation, everyone can pr the repo, and the documentation can also show on the swoole website with the pretty HTML page.

about the swoole_table, maybe you can open a new issue next time.

swoole_table is an ultra-high performance, concurrent data structure based on shared memory and locks. Used to solve multi-process / multi-thread data sharing and synchronization locking problems.

and when you use it, you must know the lifecycle of swoole, swoole's worker processes are forked from the main process, so if you create a table before server->start, all of the workers use the same swoole_table, if you create it in onXXX event callback, it's equivalent to create many tables on every worker process.
our example:

$table = new swoole_table(1024);
$table->column('fd', swoole_table::TYPE_INT);
$table->column('from_id', swoole_table::TYPE_INT);
$table->column('data', swoole_table::TYPE_STRING, 64);
$table->create();
$serv = new swoole_server('127.0.0.1', 9501);
// here
$serv->table = $table;
$serv->on('receive', function ($serv, $fd, $from_id, $data) {
    $ret = $serv->table->set($fd, array('from_id' => $data, 'fd' => $fd, 'data' => $data));
});
$serv->start();

something else, English documentation is really pool, if you can use google translation, you can see Chinese documentation temporarily.

[ghost]

@twose thank you very much, i deleted my posts, because i thought it was easier to study https://github.com/swoole/swoole-src/blob/master/swoole_table.c so i got some answers the last minutes without drive you crazy :)

But the only one i did not found actually is the type of size of table-size.
What is $table = new swoole_table(1024); 1024 here? Bytes? Rows? Bits? I didn't found any workout which ansers me.

And many thanks for $serv->table = $table; :+1: i had not found this

_EDIT_

OK - everything seems to be okay now; i found the _needed_ infos about table_size in chinese: https://wiki.swoole.com/wiki/page/254.html (with google translate) :100:

[ghost]

@twose

You wrote:

_we have a plan to create a repository in Github and use markdown to write documentation, everyone can pr the repo, and the documentation can also show on the swoole website with the pretty HTML page._

This is very nice to hear 💯 PLEASE: When deciding tag-format etc. Please check:

a) to print this side easily with a Printer (without broken pages and formatting)

b) to use (google) translator - if you chose \

 for tags for example those words would _not_ be translated from original english to target language for example :) Please have a look at this before everything is written; a automatic translation of language independet words or international naming should be avoided :) (in H1-H6 etc. too :)


👍 

Actually i am translating your great chinese documents; its very detailed and much stuff 👍 

                    

[ghost]

BTW: for all who needs documents about swoole, the original chinese documents are really great and massive stuff, from bare metal to code samples

Have for all a look at https://wiki.swoole.com/wiki/index/prid-1 :100:

I use translation to my language, its very well written and printed about 600 Pages :+1:

[doubaokun]

@flddr please check the document at https://www.swoole.co.uk/docs/

[ghost]

@doubaokun thanks

BTW: for all who needs documents about swoole, the original chinese documents are really great and massive stuff, from bare metal to code samples

Just the info for people who are feeling the english documentation is actually not enough :+1:

[ghost]

@twose

we have a plan to create a repository in Github and use markdown to write documentation, everyone can pr the repo, and the documentation can also show on the swoole website with the pretty HTML page.

What do you think about first public release time? :)

[hktr92]

it's may 2020 and me, as an enthusiast about this project, I'm pretty disappointed about the poor documentation in English. Sure, I get the idea of what does what, but here is something I've come across:

• documentation is not 100% straightforward, meaning that i have to experiment with functionality first;
• code examples are a mess. for example, I wanted to implement a pub-sub system for a project of mine and this is what i have found: https://www.swoole.co.uk/article/redis-swoole-pubsub. so I have more questions than answers:
  -- how to push a subject to redis for subscribe?
  -- how can i wrap go() in an OOP-like environment?
  -- do I have to ditch OOP for using swoole?
• didn't really found a "migration guide" on synchronous vs async usage (I'd love to migrate some of my projects to use async feats, like redis pub/sub, mysql connector, websockets, http server and workers).

for now, this is the only way of working with swoole is to copy - paste code from documentation, fix it up myself and do the trial-and-error loop to see how swoole works, and it's discouraging newbies that doesn't know / have sufficient experience to work this way.

as a reference, symfony's documentation is clear and pretty straightforward. maybe a "how-to-basic" tutorial / article would be helpful, with explanation of how stuff works, so we can all have a glimpse of how we should work / interact with this project.

[matyhtf]

@doubaokun

[doubaokun]

it's may 2020 and me, as an enthusiast about this project, I'm pretty disappointed about the poor documentation in English. Sure, I get the idea of what does what, but here is something I've come across:

• documentation is not 100% straightforward, meaning that i have to experiment with functionality first;
• code examples are a mess. for example, I wanted to implement a pub-sub system for a project of mine and this is what i have found: https://www.swoole.co.uk/article/redis-swoole-pubsub. so I have more questions than answers:
  -- how to push a subject to redis for subscribe?
  -- how can i wrap go() in an OOP-like environment?
  -- do I have to ditch OOP for using swoole?
• didn't really found a "migration guide" on synchronous vs async usage (I'd love to migrate some of my projects to use async feats, like redis pub/sub, mysql connector, websockets, http server and workers).

Coroutine and async is new design, the migration is not straight forward.

We will add more examples about these use cases.

for now, this is the only way of working with swoole is to copy - paste code from documentation, fix it up myself and do the trial-and-error loop to see how swoole works, and it's discouraging newbies that doesn't know / have sufficient experience to work this way.

as a reference, symfony's documentation is clear and pretty straightforward. maybe a "how-to-basic" tutorial / article would be helpful, with explanation of how stuff works, so we can all have a glimpse of how we should work / interact with this project.

Thanks for the suggestion. We will add more details about the internal and basic dependency knowledge at https://www.swoole.co.uk/docs/

For the correction and question about the functions, please post to the comment section.